Kumo design system, agents-ui package, Oxlint/Oxfmt migration, and code quality pass#865
Merged
Conversation
Refactor the playground examples to use the @cloudflare/kumo design system: replace custom cards, buttons, inputs, badges, banners, empty states, text and surface wrappers with kumo components; swap lucide-react icons for phosphor icons; introduce LinkProvider around BrowserRouter for RouterLink integration. Update demo markup and utility classnames to use kumo tokens and component props while preserving behavior. Remove lucide-react from examples/playground package.json and add a minimal examples/loader/package.json.
Add design documentation (design/README.md and visuals.md) and refactor the playground to consistently use Kumo UI components and patterns. Introduce an AppLink adapter in client.tsx to bridge Kumo's LinkProvider with React Router. Replace many raw HTML/unstyled elements with Kumo primitives (Button, InputArea, CodeBlock, Tabs, Switch, etc.), update Badge variants, and improve LogPanel styling and direction colors. These updates fix a Link type mismatch, unify visual/spacing behavior (workaround for Text not accepting className), and improve consistency and accessibility across demos.
Add top-level AGENTS documentation and supporting docs under design/, guides/, packages/, and several examples to describe repo structure, standards, testing, and contribution workflow. Update multiple example and guide wrangler.jsonc and playground files to align configurations and assets; add example TODO and AGENTS.md files where applicable. Remove obsolete .cursor/rules/cloudflare.mdc. These changes consolidate documentation and bring examples/configs up to date for contributors and demos.
Introduce a Cloudflare-branded "Workers" color theme and UI to select color theme and mode. - Add private workspace package @cloudflare/agents-theme with workers.css providing CSS custom properties for a Workers theme (light/dark variants). - Import the theme into playground styles and document theme usage in design/visuals.md and examples/AGENTS.md. - Update examples/playground/index.html to set default data-theme and to prevent flash by applying data-mode and data-theme on load. - Refactor the playground useTheme hook to manage mode (light/dark/system) and colorTheme (workers/kumo), persist both to localStorage, and update document attributes accordingly. - Update Sidebar to split theme controls into Mode and ColorTheme toggles (plus UI/icon changes). These changes enable a Cloudflare-branded theme for examples while preserving the ability to fall back to Kumo's default theme.
Modernize the tictactoe example: switch from .dev.vars to .env.example, mark TODOs as completed, and update README instructions. Replace the old static UI/normalize.css with a Tailwind + Kumo-based design: refactor client.tsx to use @cloudflare/kumo components and Phosphor icons, overhaul styles.css to import Tailwind/Kumo/agents-theme, and remove the bundled normalize.css. Add @cloudflare/agents-theme to package.json and enable the Tailwind Vite plugin in vite.config.ts. Clean up wrangler.jsonc assets (remove redundant "directory"). These changes standardize environment handling and modernize styling and UX for the example.
Add theme support and refactor the AI playground UI to use Kumo styles/components. Introduces a ThemeProvider and useTheme hook (wraps App), prevents FOUC by initializing data-mode in index.html, and updates body/root classes. App refactor: swap many gray utility classes for kumo tokens, replace raw buttons/SVGs with Kumo Button/Link components and WorkersAILogo, add GearIcon, consolidate agent state updates into updateState helper, cap MCP logs, simplify session ID handling, and improve Streamdown usage. Remove unused FinetuneSelector and ModelSelector components and drop tailwind config; add new runtime deps in package.json (agents-theme, streamdown/code).
Introduce a new private workspace package @cloudflare/agents-ui that bundles the Workers color theme CSS, shared React components (ConnectionIndicator, ModeToggle, Cloudflare logo), and hooks (ThemeProvider, useTheme). Replace usages of the old agents-theme with agents-ui/theme/workers.css across examples and update example package dependencies to depend on @cloudflare/agents-ui. Add a new resumable-stream-chat example (client, styles, README, vite config, wrangler config and package.json) demonstrating resumable streaming with useAgentChat; the client uses Kumo components and agents-ui components/hooks and is wrapped with ThemeProvider. Small UI and accessibility tweaks applied to playground demos (class changes like flex-shrink-0→shrink-0, layout refactors, improved header/input UI). Move the useTheme hook from the site playground into the new agents-ui package and add exports/README/tsconfig for the package. Remove the old packages/agents-theme package.json. Also rename .dev.vars.example files to .env.example and update README references to use .env. Package lock updated to reflect dependency changes.
Migrate the workflows example to use @cloudflare/agents-ui shared components and Kumo UI. Add ThemeProvider, ConnectionIndicator, ModeToggle and PoweredByAgents usage; wrap the app in ThemeProvider and load theme CSS from agents-ui. Replace legacy public/styles.css with a Tailwind + Kumo + agents-ui src/styles.css, add a small theme init script to index.html, and add @cloudflare/agents-ui and Tailwind tooling to package.json/vite config. Refactor app.tsx: unified connection status, toast timer, callAgent wrapper with local-dev error messaging, pagination deduplication, and componentize WorkflowCard/StatusBadge/WorkflowEndActions. Simplify server status mapping to a known map and update wrangler assets config for SPA not-found handling.
Switch linting/formatting tooling from Biome/Prettier to oxfmt/oxlint across the repo. Add .oxfmtrc.json and .oxlintrc.json, remove .prettierrc, .prettierignore and biome.json, and update package.json scripts and devDependencies to use oxfmt/oxlint (also update lint-staged). Replace in-source lint suppressions (biome-ignore / biome-ignore-all) with the corresponding oxlint disable comments in many source files. Apply minor formatting/whitespace fixes and a small wrangler.toml cleanup. package-lock.json was updated to reflect the dependency changes.
Delete file- and inline-level oxlint-disable comments across the repo and tighten the linter configuration. .oxlintrc.json re-enables several rules (no-inferrable-types, prefer-as-const, default-param-last, various jsx-a11y rules) and removes broad ignorePatterns for node_modules, dist, and .wrangler. Multiple source files (examples, guides, openai-sdk, packages/agents react and tests, and site/ai-playground components) had their /* oxlint-disable */ or // oxlint-disable-next-line comments removed to restore linting and accessibility checks and to clean up commented lines in JSX.
Replace generic oxlint-disable comments with specific eslint/tslint rule disables and inline justifications across the codebase, improving clarity for suppressed checks. Also apply small accessibility fixes (add htmlFor/id on labels, adjust image alt text) and add targeted jsx-a11y disables for click-only interactive elements. Other minor changes include underscoring unused parameters, scoping any usage with enable/disable comments, and small test typing adjustments. Files updated include multiple examples, site components, and packages/agents sources to reflect these lint and a11y improvements.
Tighten TypeScript types and add safer runtime checks across multiple files. .github/resolve-workspace-versions.ts: introduce a PackageJson interface, store package file metadata, and simplify dependency field handling. examples/a2a: add isAsyncIterable helper and use it to detect async streams. examples/a2a/cli: normalize caught errors (unknown -> Error), log message/code/data safely. examples/codemode: add a ToolPart interface, replace any casts, and guard clipboard writes. examples/mcp-client: narrow API response type to tools: unknown[] instead of any[]. openai-sdk/human-in-the-loop: introduce RunResultState type, type AgentStateDisplay and App state, and replace unsafe any access with null-safe checks. Overall these changes reduce any usage and improve type safety and runtime robustness.
Update dependency versions across multiple example and package manifests and refresh package-lock.json. Notable changes: bump hono to ^4.11.8 in examples, bump mcp-remote to ^0.1.38, and upgrade dev deps in openai-sdk/chess-app ( @cloudflare/vite-plugin, @vitejs/plugin-react, @types/react ). The package-lock.json was updated to lock the new versions and ensure consistent installs.
Switch linting/formatting from Biome/Prettier to Oxlint/Oxfmt (editor settings, recommended extension, build scripts updated to run `oxfmt --write`). Add/adjust packages and peers for the new agents-ui package. Make a broad code-quality pass: add runtime guards and try/catch around JSON.parse and streaming calls, strengthen error logging, replace unsafe type assertions with runtime checks, and wrap callbacks in useCallback to avoid stale closures. Improve accessibility (aria attributes, role/aria-live, labels, controls) and update docs (AGENTS.md, examples TODO, add pr.md). Miscellaneous example and component fixes across the repo to reflect the tooling and API changes.
🦋 Changeset detectedLatest commit: 9847174 The changes in this PR will be included in the next version bump. This PR includes changesets to release 4 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
commit: |
This comment was marked as resolved.
This comment was marked as resolved.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This branch modernizes the repo's UI layer, introduces shared UI infrastructure, fully migrates linting/formatting tooling from Biome/Prettier to Oxlint/Oxfmt, and makes a thorough type safety and code quality pass across the codebase.
Kumo design system adoption
@cloudflare/kumocomponents throughout (Button, InputArea, CodeBlock, Tabs, Switch, Badge, Banner, etc.), replacing raw HTML and custom styling.LinkProvider/AppLinkadapter to bridge Kumo's link component with React Router.lucide-reacticons with@phosphor-icons/react.@cloudflare/agents-ui) with CSS custom properties for Cloudflare-branded light/dark variants.useThemeto manage both mode (light/dark/system) and color theme (workers/kumo), persisted to localStorage.design/(README, visuals.md).New
@cloudflare/agents-uipackagepackages/agents-ui) bundling Workers theme CSS, shared React components (ConnectionIndicator,ModeToggle,CloudflareLogo,PoweredByAgents), and hooks (ThemeProvider,useTheme).ConnectionIndicatorincludes proper ARIA attributes (role="status",aria-live="polite").@cloudflare/kumoand@phosphor-icons/reactas peer dependencies.agents-uicomponents and Kumo UI.useAgentChat.Complete Oxlint/Oxfmt migration (Biome/Prettier fully removed)
biome.json,.prettierrc,.prettierignoreand their dev dependencies..oxlintrc.json(plugins: react, jsx-a11y, typescript, react-hooks) and.oxfmtrc.json.package.jsonscripts (lint,format,check,lint-staged).packages/agents,ai-chat,codemode,hono-agents) withoxfmt --writefor.d.tsformatting..vscode/settings.jsonto useoxc.oxc-vscodeas the default formatter; updated.vscode/extensions.jsonto recommendoxc.oxc-vscodeinstead of Prettier/Biome extensions.biome-ignoreinline comments tooxlint-disable/eslint-disableequivalents.jsx-a11yplugin rules fully.oxlint-disablehas a specific rule name and a reason comment.exhaustive-deps).Type safety improvements
.github/resolve-workspace-versions.ts— customPackageJsoninterface; try/catch aroundJSON.parse.examples/a2a/src/app.ts—isAsyncIterabletype guard for async stream detection.examples/a2a/src/cli.ts—catch (error: unknown)with proper narrowing; replaced unsafeerror as { code, data }cast with runtimeinchecks.examples/codemode/src/client.tsx—ToolPartinterface withtoolCallId;asToolPart()runtime type guard replacingas unknown asdouble assertion.examples/mcp-client/src/client.tsx—tools: unknown[]instead ofany[].openai-sdk/human-in-the-loop/src/client.tsx—RunResultStateinterface; try/catch aroundJSON.parsefor both tool arguments and serialized state; modal state cleanup when interruption resolves.tsc --noEmitwith 0 errors.Accessibility improvements
packages/agents-uiConnectionIndicator—role="status",aria-live="polite",aria-hiddenon decorative dot.examples/workflows/src/app.tsx—aria-labelon task name input, reject reason input, and toast dismiss button.examples/playground/src/layout/Sidebar.tsx—aria-expanded,aria-controlson collapsible category buttons;role="region"andaria-labelon expanded content.site/ai-playground—htmlFor/idwiring on labels, improved image alt text.jsx-a11ydisables with reasons for legitimate cases (modal backdrops, game board cells).Error handling improvements
examples/workflows/src/server.ts— try/catch around SQL metadata update operations inupdateUIStateandclearUIState.examples/resumable-stream-chat/src/client.tsx— try/catch aroundsendMessage;useCallbackfor WebSocket event handlers andsend.examples/resumable-stream-chat/src/server.ts— try/catch aroundstreamTextin theexecutecallback.examples/tictactoe/src/client.tsx— wrappedhandleCellClickandhandleNewGameinuseCallback; added them touseEffectdependency arrays to fix stale closures.examples/workflows/src/app.tsx— replaced unsafeas WorkflowCardDatatype assertion with a proper transform that validates theresultfield shape.Documentation & configuration
packages/agents/,examples/,guides/,docs/,design/.examples/TODO.mdtracking remaining cleanup items; checked off completed items..cursor/rules/cloudflare.mdc..dev.vars.exampleto.env.exampleacross examples.wrangler.jsoncacross all examples/guides/openai-sdk for consistent assets config."agents": "*"as a dependency in all examples; added@cloudflare/ai-chatand@cloudflare/codemodewhere imported."private": true.package-lock.json.Stats
Notes for reviewers
Prettier is fully removed. No Prettier references remain in source, build scripts, or editor config. All 4 package build scripts now use
oxfmt --writeto format generated.d.tsfiles. The VS Code workspace settings recommendoxc.oxc-vscodeas the formatter. Runnpm run buildto verify the full build pipeline works.Oxlint/Oxfmt are the only lint/format tools. Run
npm run lintandnpm run formatto verify. Config lives in.oxlintrc.jsonand.oxfmtrc.jsonat the repo root. Current state: 0 errors, 11 warnings (allreact-hooks/exhaustive-deps— the deps are intentionally omitted in those hooks).jsx-a11yrules are fully enabled. All violations are either fixed or have a targetedoxlint-disable-next-linewith a reason. Please fix rather than disable any new a11y warnings in future code.@cloudflare/agents-uiis a new private package atpackages/agents-ui/. It shares theme + component code between examples (workflows, resumable-stream-chat, etc.). It declares@cloudflare/kumoand@phosphor-icons/reactas peer dependencies. Reviewpackages/agents-ui/src/for the full API surface.Type safety pass was thorough. Every
anysuppression now has a specific rule name and explanation comment. Someanyremains where external SDK generics require it (e.g.,Agent<any, any>constraints, proxy/dynamic-method wrapping) — documented inline. AllJSON.parsecalls in client-facing code now have try/catch. Unsafe type assertions have been replaced with runtime checks or proper transforms.React patterns were tightened. Stale closure bugs fixed in tictactoe (moved
useCallbackdeclarations beforeuseEffectcalls, added to dep arrays). WebSocket callbacks in resumable-stream-chat wrapped inuseCallback. WorkflowsWorkflowCardnow uses a validated transform instead of a raw type assertion.The
design/directory is new. ContainsREADME.mdandvisuals.mddescribing the Kumo integration approach and Workers theme. Intended as living documentation for contributors.wrangler.jsonc changes are cosmetic. Most wrangler config changes just normalize the
assetsfield or updatecompatibility_date. No runtime behavior changes..env.examplereplaces.dev.vars.example. Aligns with newer Wrangler conventions. Existing.dev.varsfiles (gitignored) still work.