From a8d21a6c01fffd74420845797b5d51c9fdf6b955 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Mon, 25 May 2026 15:05:46 +0800
Subject: [PATCH 01/22] refactor(web): extract shared UI primitives

---
 apps/web/package.json                         |   1 +
 .../src/components/ContinueInCliButton.tsx    |  11 +-
 .../src/components/FinalizeDesignButton.tsx   |  11 +-
 apps/web/src/index.css                        |   1 +
 apps/web/src/styles/primitives.css            | 276 ------------------
 packages/AGENTS.md                            |   1 +
 packages/components/esbuild.config.ts         |  13 +
 packages/components/package.json              |  36 +++
 packages/components/src/index.ts              |   4 +
 packages/components/src/primitives.tsx        |  66 +++++
 packages/components/src/styles.css            | 275 +++++++++++++++++
 packages/components/tsconfig.json             |  19 ++
 pnpm-lock.yaml                                |  22 ++
 scripts/postinstall.mjs                       |   1 +
 14 files changed, 449 insertions(+), 288 deletions(-)
 create mode 100644 packages/components/esbuild.config.ts
 create mode 100644 packages/components/package.json
 create mode 100644 packages/components/src/index.ts
 create mode 100644 packages/components/src/primitives.tsx
 create mode 100644 packages/components/src/styles.css
 create mode 100644 packages/components/tsconfig.json

diff --git a/apps/web/package.json b/apps/web/package.json
index b64106e1a..6123f3f25 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -29,6 +29,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.32.1",
+    "@open-design/components": "workspace:*",
     "@open-design/contracts": "workspace:*",
     "@open-design/host": "workspace:*",
     "@open-design/platform": "workspace:*",
diff --git a/apps/web/src/components/ContinueInCliButton.tsx b/apps/web/src/components/ContinueInCliButton.tsx
index 7a557ac33..fd2074529 100644
--- a/apps/web/src/components/ContinueInCliButton.tsx
+++ b/apps/web/src/components/ContinueInCliButton.tsx
@@ -17,6 +17,7 @@
 // component itself.
 
 import type { DesignMdState, DesignMdStaleReason } from '../hooks/useDesignMdState';
+import { Button } from '@open-design/components';
 
 const STALE_CHIP_TEXT = 'Spec is stale — regenerate?';
 // Round 7 (mrcfps @ useDesignMdState.ts:160): malformed provenance
@@ -46,14 +47,13 @@ export function ContinueInCliButton({ designMdState, onClick }: ContinueInCliBut
     // explanation when the disabled button gets focused.
     return (
       <span className="project-actions-button-group">
-        <button
-          type="button"
+        <Button
           className="project-actions-button project-actions-button-secondary"
           disabled
           aria-describedby="continue-in-cli-disabled-hint"
         >
           Continue in CLI
-        </button>
+        </Button>
         <span
           id="continue-in-cli-disabled-hint"
           className="project-actions-disabled-hint"
@@ -67,15 +67,14 @@ export function ContinueInCliButton({ designMdState, onClick }: ContinueInCliBut
 
   return (
     <span className="project-actions-button-group">
-      <button
-        type="button"
+      <Button
         className="project-actions-button project-actions-button-secondary"
         onClick={() => {
           void onClick();
         }}
       >
         Continue in CLI
-      </button>
+      </Button>
       {designMdState.isStale ? (
         <span className="project-actions-chip" role="note" aria-label="Spec staleness">
           {chipTextForReason(designMdState.staleReason)}
diff --git a/apps/web/src/components/FinalizeDesignButton.tsx b/apps/web/src/components/FinalizeDesignButton.tsx
index 2ea8cba4c..b00cefa79 100644
--- a/apps/web/src/components/FinalizeDesignButton.tsx
+++ b/apps/web/src/components/FinalizeDesignButton.tsx
@@ -12,6 +12,7 @@
 
 import type { DesignMdState } from '../hooks/useDesignMdState';
 import type { FinalizeStatus } from '../hooks/useFinalizeProject';
+import { Button } from '@open-design/components';
 
 export interface FinalizeDesignButtonProps {
   designMdState: Pick<DesignMdState, 'exists' | 'isStale'>;
@@ -31,14 +32,13 @@ export function FinalizeDesignButton({
       <div className="project-actions-button project-actions-button-pending" role="group">
         <span className="project-actions-spinner" aria-hidden="true" />
         <span className="project-actions-label">Finalizing…</span>
-        <button
-          type="button"
+        <Button
           className="project-actions-link"
           onClick={onCancel}
           aria-label="Cancel finalize"
         >
           Cancel
-        </button>
+        </Button>
       </div>
     );
   }
@@ -57,12 +57,11 @@ export function FinalizeDesignButton({
   }
 
   return (
-    <button
-      type="button"
+    <Button
       className={`project-actions-button ${variantClass}`}
       onClick={onFinalize}
     >
       {label}
-    </button>
+    </Button>
   );
 }
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index 875e9638c..00b71c053 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -2,6 +2,7 @@
 @import './styles/design-system-flow.css';
 @import './styles/tokens.css';
 @import './styles/base.css';
+@import '@open-design/components/styles.css';
 @import './styles/primitives.css';
 @import './styles/shell.css';
 @import './styles/chat.css';
diff --git a/apps/web/src/styles/primitives.css b/apps/web/src/styles/primitives.css
index 7b7d4748f..7a8a08987 100644
--- a/apps/web/src/styles/primitives.css
+++ b/apps/web/src/styles/primitives.css
@@ -1,279 +1,3 @@
-/* -------- Buttons --------------------------------------------------- */
-button {
-  font: inherit;
-  color: var(--text);
-  background: var(--bg-panel);
-  border: 1px solid var(--border);
-  border-radius: var(--radius-sm);
-  padding: 6px 12px;
-  cursor: pointer;
-  transition: background 120ms ease, border-color 120ms ease, color 120ms ease, box-shadow 120ms ease;
-}
-button:hover:not(:disabled) { background: var(--bg-subtle); border-color: var(--border-strong); }
-button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
-
-button.primary {
-  background: var(--accent);
-  border-color: var(--accent);
-  color: white;
-  font-weight: 500;
-  box-shadow: 0 1px 0 rgba(180, 90, 59, 0.18) inset, var(--shadow-xs);
-}
-button.primary:hover:not(:disabled) {
-  background: var(--accent-hover);
-  border-color: var(--accent-hover);
-}
-button.primary-ghost {
-  background: var(--bg-panel);
-  border-color: var(--accent);
-  color: var(--accent);
-  font-weight: 500;
-}
-button.primary-ghost:hover:not(:disabled) { background: var(--accent-tint); }
-
-button.ghost {
-  background: transparent;
-  border-color: var(--border);
-  color: var(--text);
-}
-button.ghost:hover:not(:disabled) { background: var(--bg-subtle); border-color: var(--border-strong); }
-/*
- * Transient success state for ghost buttons. Used by the Media
- * Providers "Reload from daemon" button after a successful reload —
- * the button briefly turns green with a check icon for ~2s then snaps
- * back to its idle treatment, replacing what used to be a permanent
- * success paragraph under the section header. Reusable on any
- * ghost button that wants the same "did it" pulse.
- */
-button.ghost.is-success-flash {
-  border-color: var(--green-border, color-mix(in srgb, #1f9d55 32%, var(--border)));
-  background: var(--green-bg, color-mix(in srgb, #1f9d55 8%, transparent));
-  color: var(--green, #137a3d);
-}
-button.ghost.is-success-flash:hover:not(:disabled) {
-  background: var(--green-bg, color-mix(in srgb, #1f9d55 14%, transparent));
-}
-button.ghost.is-success-flash svg {
-  color: currentColor;
-}
-
-/*
- * Visually-hidden but assistive-tech accessible. We use it to keep
- * a `role="status"` live-region for actions whose visible feedback
- * is too transient (e.g. a 2s button-label flash) for a screen
- * reader to catch reliably. Borrowed from Tailwind's `sr-only` so
- * it reads as the same primitive everyone already knows.
- */
-.sr-only {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  padding: 0;
-  margin: -1px;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border: 0;
-}
-
-button.subtle {
-  background: var(--bg-subtle);
-  border-color: transparent;
-  color: var(--text);
-}
-button.subtle:hover:not(:disabled) { background: var(--bg-muted); }
-
-button.icon-btn { padding: 6px 10px; font-size: 13px; }
-button:disabled { opacity: 0.5; cursor: not-allowed; }
-
-/* -------- Inputs ---------------------------------------------------- */
-input, textarea, select {
-  font: inherit;
-  color: var(--text);
-  background: var(--bg-panel);
-  border: 1px solid var(--border);
-  border-radius: var(--radius-sm);
-  padding: 7px 10px;
-  width: 100%;
-  transition: border-color 120ms ease, box-shadow 120ms ease;
-}
-input::placeholder, textarea::placeholder { color: var(--text-faint); }
-input:focus, textarea:focus, select:focus {
-  outline: none;
-  border-color: var(--selected);
-  box-shadow: 0 0 0 3px var(--selected-soft);
-}
-/* Entry sidebar form fields keep a quieter, neutral focus so the orange
-   "Create" CTA stays the loudest thing in the panel. A low-opacity black
-   halo reads as "focused" without re-introducing the global blue/accent
-   ring. Using rgba directly because the Next CSS pipeline collapses
-   `color-mix(in srgb, var(--text) 8%, transparent)` to a solid var(--text)
-   ring (would render a 3px black band — too loud). */
-.entry-side input:focus,
-.entry-side textarea:focus,
-.entry-side select:focus {
-  border-color: var(--text);
-  box-shadow: 0 0 0 3px rgba(28, 27, 26, 0.08);
-}
-/* Native <select> on macOS uses its own intrinsic min-height that ends up
-   shorter than <input> at the same `padding: 7px 10px` rule above, so any
-   form that flex-aligns an input next to a select (e.g. the memory editor's
-   Title + Type row) renders with mismatched heights. Stripping the native
-   chrome lets the shared padding and inherited line-height compute the
-   same box dimensions as the input, then we paint our own chevron via a
-   background SVG. The chevron color is a per-theme override so it stays
-   readable against the panel in both light and dark. */
-select {
-  padding-right: 32px;
-  appearance: none;
-  -webkit-appearance: none;
-  background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' fill='none' stroke='%2374716b' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='3 5 6 8 9 5'/%3E%3C/svg%3E");
-  background-repeat: no-repeat;
-  background-position: right 10px center;
-  background-size: 12px 12px;
-}
-select::-ms-expand { display: none; }
-[data-theme='dark'] select {
-  background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' fill='none' stroke='%239a9690' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='3 5 6 8 9 5'/%3E%3C/svg%3E");
-  background-repeat: no-repeat;
-  background-position: right 10px center;
-  background-size: 12px 12px;
-}
-@media (prefers-color-scheme: dark) {
-  html:not([data-theme]) select {
-    background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' fill='none' stroke='%239a9690' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='3 5 6 8 9 5'/%3E%3C/svg%3E");
-    background-repeat: no-repeat;
-    background-position: right 10px center;
-    background-size: 12px 12px;
-  }
-}
-textarea { resize: vertical; font-family: inherit; }
-
-.od-select {
-  position: relative;
-  width: 100%;
-  min-width: 0;
-}
-.od-select-trigger {
-  width: 100%;
-  min-width: 0;
-  min-height: 36px;
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) auto;
-  align-items: center;
-  gap: 8px;
-  padding: 7px 10px;
-  font: inherit;
-  color: var(--text);
-  text-align: left;
-  background: var(--bg-panel);
-  border: 1px solid var(--border);
-  border-radius: var(--radius-sm);
-  cursor: pointer;
-  transition: border-color 120ms ease, box-shadow 120ms ease, background 120ms ease;
-}
-.od-select-trigger:hover:not(:disabled),
-.od-select-trigger[aria-expanded='true'] {
-  border-color: var(--border-strong);
-  background: var(--bg-subtle);
-}
-.od-select-trigger:focus-visible,
-.od-select-trigger[aria-expanded='true'] {
-  outline: none;
-  border-color: var(--selected);
-  box-shadow: 0 0 0 3px var(--selected-soft);
-}
-.od-select-trigger:disabled {
-  opacity: 0.55;
-  cursor: not-allowed;
-}
-.od-select-trigger svg {
-  color: var(--text-muted);
-  transition: transform 120ms ease;
-}
-.od-select-trigger[aria-expanded='true'] svg {
-  transform: rotate(180deg);
-}
-.od-select-value,
-.od-select-option-label {
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-.od-select-menu {
-  z-index: 9000;
-  padding: 4px;
-  overflow-y: auto;
-  overflow-x: hidden;
-  overscroll-behavior: contain;
-  max-width: calc(100vw - 24px);
-  background: var(--bg-panel);
-  border: 1px solid var(--border);
-  border-radius: var(--radius-sm);
-  box-shadow: var(--shadow-lg);
-}
-.od-select-menu.portal {
-  position: fixed;
-}
-.od-select-menu.inline {
-  position: absolute;
-  top: calc(100% + 4px);
-  left: 0;
-  right: 0;
-  max-height: min(280px, 48vh);
-}
-.od-select-option {
-  width: 100%;
-  min-width: 0;
-  min-height: 30px;
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) 16px;
-  align-items: center;
-  gap: 8px;
-  padding: 6px 8px;
-  color: var(--text);
-  background: transparent;
-  border: 0;
-  border-radius: 6px;
-  font: inherit;
-  font-size: 12.5px;
-  text-align: left;
-  cursor: pointer;
-}
-.od-select-option:hover:not(:disabled),
-.od-select-option.active:not(:disabled) {
-  background: var(--bg-subtle);
-}
-.od-select-option.selected {
-  color: var(--text);
-  font-weight: 600;
-}
-.od-select-option:disabled {
-  opacity: 0.45;
-  cursor: not-allowed;
-}
-.od-select-option-check {
-  display: inline-flex;
-  justify-content: center;
-  color: var(--selected);
-  opacity: 0;
-}
-.od-select-option.selected .od-select-option-check {
-  opacity: 1;
-}
-.od-select-group + .od-select-group {
-  margin-top: 4px;
-  padding-top: 4px;
-  border-top: 1px solid var(--border-soft);
-}
-.od-select-group-label {
-  padding: 6px 8px 4px;
-  color: var(--text-faint);
-  font-size: 11px;
-  font-weight: 600;
-}
-
 code {
   font-family: var(--mono);
   background: var(--bg-subtle);
diff --git a/packages/AGENTS.md b/packages/AGENTS.md
index 2b1c12353..ea13a9e30 100644
--- a/packages/AGENTS.md
+++ b/packages/AGENTS.md
@@ -5,6 +5,7 @@ Follow the root `AGENTS.md` first. This file only records module-level boundarie
 ## Package responsibilities
 
 - `packages/contracts`: web/daemon app contract layer. Keep it pure TypeScript; it must not depend on Next.js, Express, Node filesystem/process APIs, browser APIs, SQLite, daemon internals, or the sidecar control-plane protocol.
+- `packages/components`: shared React UI primitives and primitive CSS. It may depend on React types/runtime only; keep product workflows and app-specific layout/styling in the apps.
 - `packages/host`: web/desktop host bridge contract. It models renderer-facing host capabilities and helpers while keeping `window.__od__` access out of app UI code.
 - `packages/sidecar-proto`: Open Design sidecar business protocol. Owns app/mode/source constants, namespace validation, stamp descriptor/fields/flags, IPC message schema, status shapes, error semantics, and default product path constants.
 - `packages/sidecar`: generic sidecar runtime primitives. Includes bootstrap, IPC transport, path/runtime resolution, launch env, and JSON runtime file helpers; it must not hard-code Open Design app keys or IPC business messages.
diff --git a/packages/components/esbuild.config.ts b/packages/components/esbuild.config.ts
new file mode 100644
index 000000000..e63dab55e
--- /dev/null
+++ b/packages/components/esbuild.config.ts
@@ -0,0 +1,13 @@
+import { build } from 'esbuild';
+
+await build({
+  bundle: true,
+  entryPoints: ['./src/index.ts'],
+  format: 'esm',
+  outbase: './src',
+  outdir: './dist',
+  outExtension: { '.js': '.mjs' },
+  packages: 'external',
+  platform: 'browser',
+  target: 'es2022',
+});
diff --git a/packages/components/package.json b/packages/components/package.json
new file mode 100644
index 000000000..422e9d3d2
--- /dev/null
+++ b/packages/components/package.json
@@ -0,0 +1,36 @@
+{
+  "name": "@open-design/components",
+  "version": "0.8.0",
+  "private": true,
+  "type": "module",
+  "description": "Shared Open Design React UI primitives.",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/styles.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./styles.css": "./src/styles.css"
+  },
+  "scripts": {
+    "build": "tsx ./esbuild.config.ts && tsc -p tsconfig.json --emitDeclarationOnly",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "react": "18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "18.3.28",
+    "esbuild": "0.28.0",
+    "tsx": "4.22.3",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": "~24"
+  }
+}
diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
new file mode 100644
index 000000000..9d2d547f6
--- /dev/null
+++ b/packages/components/src/index.ts
@@ -0,0 +1,4 @@
+export { Button } from './primitives.js';
+export type { ButtonProps, ButtonSize, ButtonVariant } from './primitives.js';
+export { Input, Select, Textarea, VisuallyHidden } from './primitives.js';
+export type { InputProps, SelectProps, TextareaProps, VisuallyHiddenProps } from './primitives.js';
diff --git a/packages/components/src/primitives.tsx b/packages/components/src/primitives.tsx
new file mode 100644
index 000000000..f03e50061
--- /dev/null
+++ b/packages/components/src/primitives.tsx
@@ -0,0 +1,66 @@
+import { forwardRef } from 'react';
+import type {
+  ButtonHTMLAttributes,
+  InputHTMLAttributes,
+  ReactNode,
+  SelectHTMLAttributes,
+  TextareaHTMLAttributes,
+} from 'react';
+
+export type ButtonVariant = 'default' | 'primary' | 'primary-ghost' | 'ghost' | 'subtle';
+export type ButtonSize = 'default' | 'compact' | 'icon';
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+}
+
+function joinClassNames(...classNames: Array<string | false | null | undefined>) {
+  return classNames.filter(Boolean).join(' ') || undefined;
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  { className, type = 'button', variant = 'default', size = 'default', ...props },
+  ref,
+) {
+  return (
+    <button
+      ref={ref}
+      type={type}
+      className={joinClassNames(
+        variant !== 'default' && variant,
+        size === 'compact' && 'compact',
+        size === 'icon' && 'icon-btn',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+export type InputProps = InputHTMLAttributes<HTMLInputElement>;
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(props, ref) {
+  return <input ref={ref} {...props} />;
+});
+
+export type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement>;
+
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function Textarea(props, ref) {
+  return <textarea ref={ref} {...props} />;
+});
+
+export type SelectProps = SelectHTMLAttributes<HTMLSelectElement>;
+
+export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select(props, ref) {
+  return <select ref={ref} {...props} />;
+});
+
+export interface VisuallyHiddenProps {
+  children: ReactNode;
+  className?: string;
+}
+
+export function VisuallyHidden({ children, className }: VisuallyHiddenProps) {
+  return <span className={joinClassNames('sr-only', className)}>{children}</span>;
+}
diff --git a/packages/components/src/styles.css b/packages/components/src/styles.css
new file mode 100644
index 000000000..fe1fcfb04
--- /dev/null
+++ b/packages/components/src/styles.css
@@ -0,0 +1,275 @@
+/* -------- Buttons --------------------------------------------------- */
+button {
+  font: inherit;
+  color: var(--text);
+  background: var(--bg-panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 6px 12px;
+  cursor: pointer;
+  transition: background 120ms ease, border-color 120ms ease, color 120ms ease, box-shadow 120ms ease;
+}
+button:hover:not(:disabled) { background: var(--bg-subtle); border-color: var(--border-strong); }
+button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+button.primary {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: white;
+  font-weight: 500;
+  box-shadow: 0 1px 0 rgba(180, 90, 59, 0.18) inset, var(--shadow-xs);
+}
+button.primary:hover:not(:disabled) {
+  background: var(--accent-hover);
+  border-color: var(--accent-hover);
+}
+button.primary-ghost {
+  background: var(--bg-panel);
+  border-color: var(--accent);
+  color: var(--accent);
+  font-weight: 500;
+}
+button.primary-ghost:hover:not(:disabled) { background: var(--accent-tint); }
+
+button.ghost {
+  background: transparent;
+  border-color: var(--border);
+  color: var(--text);
+}
+button.ghost:hover:not(:disabled) { background: var(--bg-subtle); border-color: var(--border-strong); }
+/*
+ * Transient success state for ghost buttons. Used by the Media
+ * Providers "Reload from daemon" button after a successful reload —
+ * the button briefly turns green with a check icon for ~2s then snaps
+ * back to its idle treatment, replacing what used to be a permanent
+ * success paragraph under the section header. Reusable on any
+ * ghost button that wants the same "did it" pulse.
+ */
+button.ghost.is-success-flash {
+  border-color: var(--green-border, color-mix(in srgb, #1f9d55 32%, var(--border)));
+  background: var(--green-bg, color-mix(in srgb, #1f9d55 8%, transparent));
+  color: var(--green, #137a3d);
+}
+button.ghost.is-success-flash:hover:not(:disabled) {
+  background: var(--green-bg, color-mix(in srgb, #1f9d55 14%, transparent));
+}
+button.ghost.is-success-flash svg {
+  color: currentColor;
+}
+
+/*
+ * Visually-hidden but assistive-tech accessible. We use it to keep
+ * a `role="status"` live-region for actions whose visible feedback
+ * is too transient (e.g. a 2s button-label flash) for a screen
+ * reader to catch reliably. Borrowed from Tailwind's `sr-only` so
+ * it reads as the same primitive everyone already knows.
+ */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+button.subtle {
+  background: var(--bg-subtle);
+  border-color: transparent;
+  color: var(--text);
+}
+button.subtle:hover:not(:disabled) { background: var(--bg-muted); }
+
+button.icon-btn { padding: 6px 10px; font-size: 13px; }
+button:disabled { opacity: 0.5; cursor: not-allowed; }
+
+/* -------- Inputs ---------------------------------------------------- */
+input, textarea, select {
+  font: inherit;
+  color: var(--text);
+  background: var(--bg-panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 7px 10px;
+  width: 100%;
+  transition: border-color 120ms ease, box-shadow 120ms ease;
+}
+input::placeholder, textarea::placeholder { color: var(--text-faint); }
+input:focus, textarea:focus, select:focus {
+  outline: none;
+  border-color: var(--selected);
+  box-shadow: 0 0 0 3px var(--selected-soft);
+}
+/* Entry sidebar form fields keep a quieter, neutral focus so the orange
+   "Create" CTA stays the loudest thing in the panel. A low-opacity black
+   halo reads as "focused" without re-introducing the global blue/accent
+   ring. Using rgba directly because the Next CSS pipeline collapses
+   `color-mix(in srgb, var(--text) 8%, transparent)` to a solid var(--text)
+   ring (would render a 3px black band — too loud). */
+.entry-side input:focus,
+.entry-side textarea:focus,
+.entry-side select:focus {
+  border-color: var(--text);
+  box-shadow: 0 0 0 3px rgba(28, 27, 26, 0.08);
+}
+/* Native <select> on macOS uses its own intrinsic min-height that ends up
+   shorter than <input> at the same `padding: 7px 10px` rule above, so any
+   form that flex-aligns an input next to a select (e.g. the memory editor's
+   Title + Type row) renders with mismatched heights. Stripping the native
+   chrome lets the shared padding and inherited line-height compute the
+   same box dimensions as the input, then we paint our own chevron via a
+   background SVG. The chevron color is a per-theme override so it stays
+   readable against the panel in both light and dark. */
+select {
+  padding-right: 32px;
+  appearance: none;
+  -webkit-appearance: none;
+  background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' fill='none' stroke='%2374716b' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='3 5 6 8 9 5'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 10px center;
+  background-size: 12px 12px;
+}
+select::-ms-expand { display: none; }
+[data-theme='dark'] select {
+  background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' fill='none' stroke='%239a9690' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='3 5 6 8 9 5'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 10px center;
+  background-size: 12px 12px;
+}
+@media (prefers-color-scheme: dark) {
+  html:not([data-theme]) select {
+    background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' fill='none' stroke='%239a9690' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='3 5 6 8 9 5'/%3E%3C/svg%3E");
+    background-repeat: no-repeat;
+    background-position: right 10px center;
+    background-size: 12px 12px;
+  }
+}
+textarea { resize: vertical; font-family: inherit; }
+
+.od-select {
+  position: relative;
+  width: 100%;
+  min-width: 0;
+}
+.od-select-trigger {
+  width: 100%;
+  min-width: 0;
+  min-height: 36px;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 8px;
+  padding: 7px 10px;
+  font: inherit;
+  color: var(--text);
+  text-align: left;
+  background: var(--bg-panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition: border-color 120ms ease, box-shadow 120ms ease, background 120ms ease;
+}
+.od-select-trigger:hover:not(:disabled),
+.od-select-trigger[aria-expanded='true'] {
+  border-color: var(--border-strong);
+  background: var(--bg-subtle);
+}
+.od-select-trigger:focus-visible,
+.od-select-trigger[aria-expanded='true'] {
+  outline: none;
+  border-color: var(--selected);
+  box-shadow: 0 0 0 3px var(--selected-soft);
+}
+.od-select-trigger:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+.od-select-trigger svg {
+  color: var(--text-muted);
+  transition: transform 120ms ease;
+}
+.od-select-trigger[aria-expanded='true'] svg {
+  transform: rotate(180deg);
+}
+.od-select-value,
+.od-select-option-label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.od-select-menu {
+  z-index: 9000;
+  padding: 4px;
+  overflow-y: auto;
+  overflow-x: hidden;
+  overscroll-behavior: contain;
+  max-width: calc(100vw - 24px);
+  background: var(--bg-panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  box-shadow: var(--shadow-lg);
+}
+.od-select-menu.portal {
+  position: fixed;
+}
+.od-select-menu.inline {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  right: 0;
+  max-height: min(280px, 48vh);
+}
+.od-select-option {
+  width: 100%;
+  min-width: 0;
+  min-height: 30px;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 16px;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 8px;
+  color: var(--text);
+  background: transparent;
+  border: 0;
+  border-radius: 6px;
+  font: inherit;
+  font-size: 12.5px;
+  text-align: left;
+  cursor: pointer;
+}
+.od-select-option:hover:not(:disabled),
+.od-select-option.active:not(:disabled) {
+  background: var(--bg-subtle);
+}
+.od-select-option.selected {
+  color: var(--text);
+  font-weight: 600;
+}
+.od-select-option:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+.od-select-option-check {
+  display: inline-flex;
+  justify-content: center;
+  color: var(--selected);
+  opacity: 0;
+}
+.od-select-option.selected .od-select-option-check {
+  opacity: 1;
+}
+.od-select-group + .od-select-group {
+  margin-top: 4px;
+  padding-top: 4px;
+  border-top: 1px solid var(--border-soft);
+}
+.od-select-group-label {
+  padding: 6px 8px 4px;
+  color: var(--text-faint);
+  font-size: 11px;
+  font-weight: 600;
+}
diff --git a/packages/components/tsconfig.json b/packages/components/tsconfig.json
new file mode 100644
index 000000000..ba21ed249
--- /dev/null
+++ b/packages/components/tsconfig.json
@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e14ccdc99..5c7574f3a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -260,6 +260,9 @@ importers:
       '@anthropic-ai/sdk':
         specifier: 0.32.1
         version: 0.32.1
+      '@open-design/components':
+        specifier: workspace:*
+        version: link:../../packages/components
       '@open-design/contracts':
         specifier: workspace:*
         version: link:../../packages/contracts
@@ -377,6 +380,25 @@ importers:
         specifier: 4.1.6
         version: 4.1.6(@opentelemetry/api@1.9.1)(@types/node@20.19.39)(jsdom@29.1.1)(vite@7.3.3(@types/node@20.19.39)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.22.3)(yaml@2.9.0))
 
+  packages/components:
+    dependencies:
+      react:
+        specifier: 18.3.1
+        version: 18.3.1
+    devDependencies:
+      '@types/react':
+        specifier: 18.3.28
+        version: 18.3.28
+      esbuild:
+        specifier: 0.28.0
+        version: 0.28.0
+      tsx:
+        specifier: 4.22.3
+        version: 4.22.3
+      typescript:
+        specifier: 5.9.3
+        version: 5.9.3
+
   packages/contracts:
     dependencies:
       zod:
diff --git a/scripts/postinstall.mjs b/scripts/postinstall.mjs
index dc55364cd..0fb68ee9d 100644
--- a/scripts/postinstall.mjs
+++ b/scripts/postinstall.mjs
@@ -8,6 +8,7 @@ const repoRoot = resolve(scriptDir, "..");
 
 const buildTargets = [
   "packages/contracts",
+  "packages/components",
   "packages/platform",
   "packages/download",
   "packages/host",

From c85bffbb971b505ea9fe020265a6a120e194f9ad Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Mon, 25 May 2026 15:12:57 +0800
Subject: [PATCH 02/22] fix(web): include components in packaged builds

---
 apps/web/tests/helpers/read-expanded-css.ts | 7 ++++++-
 flake.nix                                   | 1 +
 nix/package-web.nix                         | 1 +
 3 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/apps/web/tests/helpers/read-expanded-css.ts b/apps/web/tests/helpers/read-expanded-css.ts
index 4b2c9bfd5..e16707c37 100644
--- a/apps/web/tests/helpers/read-expanded-css.ts
+++ b/apps/web/tests/helpers/read-expanded-css.ts
@@ -1,6 +1,10 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
+const packageCssImports = new Map([
+  ['@open-design/components/styles.css', join(process.cwd(), '../../packages/components/src/styles.css')],
+]);
+
 function expandCssFile(filePath: string, seen = new Set<string>()): string {
   const key = filePath;
   if (seen.has(key)) {
@@ -12,7 +16,8 @@ function expandCssFile(filePath: string, seen = new Set<string>()): string {
   return css.replace(/@import\s+(?:url\(([^)]+)\)|(['"])([^'"]+)\2);/g, (_match, urlImport, _quote, quotedImport) => {
     const specifier = (quotedImport ?? urlImport ?? '').trim().replace(/^['"]|['"]$/g, '');
     if (!specifier.startsWith('./') && !specifier.startsWith('../')) {
-      return '';
+      const packageCssPath = packageCssImports.get(specifier);
+      return packageCssPath == null ? '' : expandCssFile(packageCssPath, seen);
     }
     return expandCssFile(join(dirname(filePath), specifier), seen);
   });
diff --git a/flake.nix b/flake.nix
index 5c256f04d..482f9e9d8 100644
--- a/flake.nix
+++ b/flake.nix
@@ -62,6 +62,7 @@
         "pnpm-workspace.yaml"
         "tsconfig.json"
         "apps/web"
+        "packages/components"
         "packages/contracts"
         "packages/host"
         "packages/platform"
diff --git a/nix/package-web.nix b/nix/package-web.nix
index dfd2fb4f4..84dbf2cfa 100644
--- a/nix/package-web.nix
+++ b/nix/package-web.nix
@@ -51,6 +51,7 @@ in
     buildPhase = ''
       runHook preBuild
       for target in \
+        packages/components \
         packages/contracts \
         packages/host \
         packages/sidecar-proto \

From 1b29056a7fcc1de11d67a30bc30ea19dbc2abb38 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Mon, 25 May 2026 15:18:03 +0800
Subject: [PATCH 03/22] fix(nix): refresh daemon pnpm deps hash

---
 nix/pnpm-deps.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nix/pnpm-deps.nix b/nix/pnpm-deps.nix
index b1526dbcb..8824a4676 100644
--- a/nix/pnpm-deps.nix
+++ b/nix/pnpm-deps.nix
@@ -8,6 +8,6 @@
   # 1. Temporarily set the consuming `hash = lib.fakeHash;`
   # 2. Run the relevant nix build/flake check
   # 3. Copy the expected hash printed by Nix into the matching field below
-  daemonHash = "sha256-enohbA0Ha41vTime/L7oa8S7wX6P2+aQAc2MpvtYLcE=";
+  daemonHash = "sha256-yJQaKdVNPEyqkLA8AnzhLR/PkIGJI0t9egJoUe7R1tU=";
   webHash = "sha256-74loUCL+WcaZO4AAMnSpNeBhDz1Y9TMgFRPbyaOfPAk=";
 }

From efee50579ce4f4f2e714181b6e996d8dea0e90f9 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Mon, 25 May 2026 15:29:21 +0800
Subject: [PATCH 04/22] fix(components): trim unused primitive exports

Generated-By: looper 0.9.0 (runner=fixer, agent=opencode)
---
 packages/components/src/index.ts       |  4 ++--
 packages/components/src/primitives.tsx | 29 ++------------------------
 2 files changed, 4 insertions(+), 29 deletions(-)

diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
index 9d2d547f6..e2e6cc429 100644
--- a/packages/components/src/index.ts
+++ b/packages/components/src/index.ts
@@ -1,4 +1,4 @@
 export { Button } from './primitives.js';
 export type { ButtonProps, ButtonSize, ButtonVariant } from './primitives.js';
-export { Input, Select, Textarea, VisuallyHidden } from './primitives.js';
-export type { InputProps, SelectProps, TextareaProps, VisuallyHiddenProps } from './primitives.js';
+export { VisuallyHidden } from './primitives.js';
+export type { VisuallyHiddenProps } from './primitives.js';
diff --git a/packages/components/src/primitives.tsx b/packages/components/src/primitives.tsx
index f03e50061..5f8b7bca8 100644
--- a/packages/components/src/primitives.tsx
+++ b/packages/components/src/primitives.tsx
@@ -1,14 +1,8 @@
 import { forwardRef } from 'react';
-import type {
-  ButtonHTMLAttributes,
-  InputHTMLAttributes,
-  ReactNode,
-  SelectHTMLAttributes,
-  TextareaHTMLAttributes,
-} from 'react';
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
 
 export type ButtonVariant = 'default' | 'primary' | 'primary-ghost' | 'ghost' | 'subtle';
-export type ButtonSize = 'default' | 'compact' | 'icon';
+export type ButtonSize = 'default' | 'icon';
 
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   variant?: ButtonVariant;
@@ -29,7 +23,6 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button
       type={type}
       className={joinClassNames(
         variant !== 'default' && variant,
-        size === 'compact' && 'compact',
         size === 'icon' && 'icon-btn',
         className,
       )}
@@ -38,24 +31,6 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button
   );
 });
 
-export type InputProps = InputHTMLAttributes<HTMLInputElement>;
-
-export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(props, ref) {
-  return <input ref={ref} {...props} />;
-});
-
-export type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement>;
-
-export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function Textarea(props, ref) {
-  return <textarea ref={ref} {...props} />;
-});
-
-export type SelectProps = SelectHTMLAttributes<HTMLSelectElement>;
-
-export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select(props, ref) {
-  return <select ref={ref} {...props} />;
-});
-
 export interface VisuallyHiddenProps {
   children: ReactNode;
   className?: string;

From aa9f71bae9116118649b256e012d366450d5028c Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Mon, 25 May 2026 18:58:36 +0800
Subject: [PATCH 05/22] refactor(components): split primitives into modules

---
 apps/web/next.config.ts                       |  1 +
 packages/components/esbuild.config.ts         |  4 +
 packages/components/package.json              |  4 +-
 packages/components/src/button.module.css     | 75 +++++++++++++++++++
 packages/components/src/button.tsx            | 45 +++++++++++
 packages/components/src/class-names.ts        |  3 +
 packages/components/src/css-modules.d.ts      |  4 +
 packages/components/src/index.ts              |  8 +-
 packages/components/src/primitives.tsx        | 45 +----------
 .../components/src/visually-hidden.module.css | 11 +++
 packages/components/src/visually-hidden.tsx   | 13 ++++
 11 files changed, 166 insertions(+), 47 deletions(-)
 create mode 100644 packages/components/src/button.module.css
 create mode 100644 packages/components/src/button.tsx
 create mode 100644 packages/components/src/class-names.ts
 create mode 100644 packages/components/src/css-modules.d.ts
 create mode 100644 packages/components/src/visually-hidden.module.css
 create mode 100644 packages/components/src/visually-hidden.tsx

diff --git a/apps/web/next.config.ts b/apps/web/next.config.ts
index 549b1ca73..d2c08826a 100644
--- a/apps/web/next.config.ts
+++ b/apps/web/next.config.ts
@@ -162,6 +162,7 @@ const nextConfig: NextConfig = {
   // to inject chunk IDs, upload to PostHog, and ALWAYS delete the .map files
   // before packaging so source never ships inside an installer.
   productionBrowserSourceMaps: true,
+  transpilePackages: ['@open-design/components'],
   turbopack: {
     root: WORKSPACE_ROOT,
   },
diff --git a/packages/components/esbuild.config.ts b/packages/components/esbuild.config.ts
index e63dab55e..e2326c36d 100644
--- a/packages/components/esbuild.config.ts
+++ b/packages/components/esbuild.config.ts
@@ -1,5 +1,9 @@
+import { rmSync } from 'node:fs';
+
 import { build } from 'esbuild';
 
+rmSync('./dist', { force: true, recursive: true });
+
 await build({
   bundle: true,
   entryPoints: ['./src/index.ts'],
diff --git a/packages/components/package.json b/packages/components/package.json
index 422e9d3d2..4c3cd1cad 100644
--- a/packages/components/package.json
+++ b/packages/components/package.json
@@ -12,8 +12,8 @@
   ],
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.mjs"
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
     },
     "./styles.css": "./src/styles.css"
   },
diff --git a/packages/components/src/button.module.css b/packages/components/src/button.module.css
new file mode 100644
index 000000000..a74bd40e3
--- /dev/null
+++ b/packages/components/src/button.module.css
@@ -0,0 +1,75 @@
+.button {
+  font: inherit;
+  color: var(--text);
+  background: var(--bg-panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 6px 12px;
+  cursor: pointer;
+  transition: background 120ms ease, border-color 120ms ease, color 120ms ease, box-shadow 120ms ease;
+}
+
+.button:hover:not(:disabled) {
+  background: var(--bg-subtle);
+  border-color: var(--border-strong);
+}
+
+.button:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+.primary {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: white;
+  font-weight: 500;
+  box-shadow: 0 1px 0 rgba(180, 90, 59, 0.18) inset, var(--shadow-xs);
+}
+
+.primary:hover:not(:disabled) {
+  background: var(--accent-hover);
+  border-color: var(--accent-hover);
+}
+
+.primaryGhost {
+  background: var(--bg-panel);
+  border-color: var(--accent);
+  color: var(--accent);
+  font-weight: 500;
+}
+
+.primaryGhost:hover:not(:disabled) {
+  background: var(--accent-tint);
+}
+
+.ghost {
+  background: transparent;
+  border-color: var(--border);
+  color: var(--text);
+}
+
+.ghost:hover:not(:disabled) {
+  background: var(--bg-subtle);
+  border-color: var(--border-strong);
+}
+
+.subtle {
+  background: var(--bg-subtle);
+  border-color: transparent;
+  color: var(--text);
+}
+
+.subtle:hover:not(:disabled) {
+  background: var(--bg-muted);
+}
+
+.icon {
+  padding: 6px 10px;
+  font-size: 13px;
+}
+
+.button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
diff --git a/packages/components/src/button.tsx b/packages/components/src/button.tsx
new file mode 100644
index 000000000..6f938e581
--- /dev/null
+++ b/packages/components/src/button.tsx
@@ -0,0 +1,45 @@
+import { forwardRef } from 'react';
+import type { ButtonHTMLAttributes } from 'react';
+
+import { joinClassNames } from './class-names.js';
+import styles from './button.module.css';
+
+export type ButtonVariant = 'default' | 'primary' | 'primary-ghost' | 'ghost' | 'subtle';
+export type ButtonSize = 'default' | 'icon';
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+}
+
+const variantClassNames: Record<ButtonVariant, string | undefined> = {
+  default: undefined,
+  primary: styles.primary,
+  'primary-ghost': styles.primaryGhost,
+  ghost: styles.ghost,
+  subtle: styles.subtle,
+};
+
+const sizeClassNames: Record<ButtonSize, string | undefined> = {
+  default: undefined,
+  icon: styles.icon,
+};
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  { className, type = 'button', variant = 'default', size = 'default', ...props },
+  ref,
+) {
+  return (
+    <button
+      ref={ref}
+      type={type}
+      className={joinClassNames(
+        styles.button,
+        variantClassNames[variant],
+        sizeClassNames[size],
+        className,
+      )}
+      {...props}
+    />
+  );
+});
diff --git a/packages/components/src/class-names.ts b/packages/components/src/class-names.ts
new file mode 100644
index 000000000..ca9c971b3
--- /dev/null
+++ b/packages/components/src/class-names.ts
@@ -0,0 +1,3 @@
+export function joinClassNames(...classNames: Array<string | false | null | undefined>) {
+  return classNames.filter(Boolean).join(' ') || undefined;
+}
diff --git a/packages/components/src/css-modules.d.ts b/packages/components/src/css-modules.d.ts
new file mode 100644
index 000000000..ab57c3452
--- /dev/null
+++ b/packages/components/src/css-modules.d.ts
@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>;
+  export default classes;
+}
diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
index e2e6cc429..68782c381 100644
--- a/packages/components/src/index.ts
+++ b/packages/components/src/index.ts
@@ -1,4 +1,4 @@
-export { Button } from './primitives.js';
-export type { ButtonProps, ButtonSize, ButtonVariant } from './primitives.js';
-export { VisuallyHidden } from './primitives.js';
-export type { VisuallyHiddenProps } from './primitives.js';
+export { Button } from './button.js';
+export type { ButtonProps, ButtonSize, ButtonVariant } from './button.js';
+export { VisuallyHidden } from './visually-hidden.js';
+export type { VisuallyHiddenProps } from './visually-hidden.js';
diff --git a/packages/components/src/primitives.tsx b/packages/components/src/primitives.tsx
index 5f8b7bca8..68782c381 100644
--- a/packages/components/src/primitives.tsx
+++ b/packages/components/src/primitives.tsx
@@ -1,41 +1,4 @@
-import { forwardRef } from 'react';
-import type { ButtonHTMLAttributes, ReactNode } from 'react';
-
-export type ButtonVariant = 'default' | 'primary' | 'primary-ghost' | 'ghost' | 'subtle';
-export type ButtonSize = 'default' | 'icon';
-
-export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  variant?: ButtonVariant;
-  size?: ButtonSize;
-}
-
-function joinClassNames(...classNames: Array<string | false | null | undefined>) {
-  return classNames.filter(Boolean).join(' ') || undefined;
-}
-
-export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
-  { className, type = 'button', variant = 'default', size = 'default', ...props },
-  ref,
-) {
-  return (
-    <button
-      ref={ref}
-      type={type}
-      className={joinClassNames(
-        variant !== 'default' && variant,
-        size === 'icon' && 'icon-btn',
-        className,
-      )}
-      {...props}
-    />
-  );
-});
-
-export interface VisuallyHiddenProps {
-  children: ReactNode;
-  className?: string;
-}
-
-export function VisuallyHidden({ children, className }: VisuallyHiddenProps) {
-  return <span className={joinClassNames('sr-only', className)}>{children}</span>;
-}
+export { Button } from './button.js';
+export type { ButtonProps, ButtonSize, ButtonVariant } from './button.js';
+export { VisuallyHidden } from './visually-hidden.js';
+export type { VisuallyHiddenProps } from './visually-hidden.js';
diff --git a/packages/components/src/visually-hidden.module.css b/packages/components/src/visually-hidden.module.css
new file mode 100644
index 000000000..54092d69c
--- /dev/null
+++ b/packages/components/src/visually-hidden.module.css
@@ -0,0 +1,11 @@
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
diff --git a/packages/components/src/visually-hidden.tsx b/packages/components/src/visually-hidden.tsx
new file mode 100644
index 000000000..640881e53
--- /dev/null
+++ b/packages/components/src/visually-hidden.tsx
@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+
+import { joinClassNames } from './class-names.js';
+import styles from './visually-hidden.module.css';
+
+export interface VisuallyHiddenProps {
+  children: ReactNode;
+  className?: string;
+}
+
+export function VisuallyHidden({ children, className }: VisuallyHiddenProps) {
+  return <span className={joinClassNames(styles.visuallyHidden, className)}>{children}</span>;
+}

From 932ce5d3a52acfe320f32826eede69b66d06636a Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Mon, 25 May 2026 19:18:49 +0800
Subject: [PATCH 06/22] fix(web): restore finalize cancel link

Generated-By: looper 0.9.0 (runner=fixer, agent=opencode)
---
 apps/web/src/components/FinalizeDesignButton.tsx | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/FinalizeDesignButton.tsx b/apps/web/src/components/FinalizeDesignButton.tsx
index b00cefa79..548179046 100644
--- a/apps/web/src/components/FinalizeDesignButton.tsx
+++ b/apps/web/src/components/FinalizeDesignButton.tsx
@@ -32,13 +32,14 @@ export function FinalizeDesignButton({
       <div className="project-actions-button project-actions-button-pending" role="group">
         <span className="project-actions-spinner" aria-hidden="true" />
         <span className="project-actions-label">Finalizing…</span>
-        <Button
+        <button
+          type="button"
           className="project-actions-link"
           onClick={onCancel}
           aria-label="Cancel finalize"
         >
           Cancel
-        </Button>
+        </button>
       </div>
     );
   }

From b69a58606d16ff97ec542c2ce53d7ed7523fadd8 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Mon, 25 May 2026 21:19:52 +0800
Subject: [PATCH 07/22] docs: prefer shared web components

---
 AGENTS.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index d48346baf..338bf6f0d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -152,6 +152,14 @@ root `pnpm tools-pr` script without a new explicit maintainer decision.
 - Keep global class names only for deliberate shared contracts: reusable primitives, theme hooks, third-party/content styling, cross-component layout, or selectors that rely on global cascade/specificity. Document any new global selector group with its owning feature.
 - CSS refactors must preserve cascade semantics. For mechanical splits, verify expanded import content/order matches the previous stylesheet; for CSS Module migrations, validate the affected UI path with `pnpm --filter @open-design/web typecheck` and a focused build/test or visual check when practical.
 
+## Web component reuse
+
+- New `apps/web` UI should reuse shared primitives from `@open-design/components` when one exists instead of styling plain HTML elements directly. For example, use `Button` for app buttons and `VisuallyHidden` for screen-reader-only text/status content.
+- Do not add new raw primitive classes such as `primary`, `primary-ghost`, `ghost`, `subtle`, `icon-btn`, or `sr-only` for new UI. Those classes are legacy compatibility surface for existing markup until it is migrated.
+- If a needed primitive is missing, prefer adding a small focused primitive to `packages/components` with colocated CSS Modules, then consume it from the app. Keep product-specific layout and workflow styling in the app, not in `packages/components`.
+- Keep semantic plain HTML when it is content markup or a specialized control that the shared package does not model yet; do not force a migration that would hide native behavior or make a custom widget harder to reason about.
+- `apps/web` transpiles `@open-design/components` from source during dev, so component and CSS Module edits should work through the normal web dev loop without rebuilding the package.
+
 ## i18n keys
 
 - `apps/web/src/i18n/types.ts` is the typed `Dict`; every key must be defined in all 18 locale files under `apps/web/src/i18n/locales/*.ts` (`ar`, `de`, `en`, `es-ES`, `fa`, `fr`, `hu`, `id`, `ja`, `ko`, `pl`, `pt-BR`, `ru`, `th`, `tr`, `uk`, `zh-CN`, `zh-TW`). Add the key to `types.ts` first; missing translations produce a typecheck error.

From 5b708c31a3ad9917e479969f841aa2379704b966 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Mon, 25 May 2026 22:02:39 +0800
Subject: [PATCH 08/22] refactor(web): migrate easy primitives

---
 apps/web/src/components/AgentPicker.tsx       | 15 ++--
 .../src/components/BoardComposerPopover.tsx   | 28 +++----
 apps/web/src/components/ChatComposer.tsx      |  7 +-
 apps/web/src/components/ConnectorsBrowser.tsx |  3 +-
 apps/web/src/components/DesignFilesPanel.tsx  |  5 +-
 apps/web/src/components/DesignSystemFlow.tsx  | 82 +++++++++----------
 apps/web/src/components/DesignSystemsTab.tsx  |  8 +-
 apps/web/src/components/FileViewer.tsx        | 52 ++++++------
 apps/web/src/components/FileWorkspace.tsx     | 21 ++---
 apps/web/src/components/McpClientSection.tsx  | 26 +++---
 apps/web/src/components/MemorySection.tsx     | 12 +--
 .../components/MissingBrandFontsBanner.tsx    |  9 +-
 apps/web/src/components/PasteTextDialog.tsx   | 11 +--
 apps/web/src/components/SettingsDialog.tsx    |  9 +-
 apps/web/src/components/SketchEditor.tsx      | 32 ++++----
 apps/web/src/components/SkillsSection.tsx     | 15 ++--
 .../components/plugins-home/PluginCard.tsx    |  3 +-
 packages/components/src/button.tsx            | 12 +--
 .../components/src/form-controls.module.css   | 49 +++++++++++
 packages/components/src/form-controls.tsx     | 32 ++++++++
 packages/components/src/index.ts              | 10 ++-
 packages/components/src/primitives.tsx        | 10 ++-
 packages/components/src/visually-hidden.tsx   | 11 ++-
 23 files changed, 274 insertions(+), 188 deletions(-)
 create mode 100644 packages/components/src/form-controls.module.css
 create mode 100644 packages/components/src/form-controls.tsx

diff --git a/apps/web/src/components/AgentPicker.tsx b/apps/web/src/components/AgentPicker.tsx
index 38a0fe4f0..722e8eaa9 100644
--- a/apps/web/src/components/AgentPicker.tsx
+++ b/apps/web/src/components/AgentPicker.tsx
@@ -1,3 +1,4 @@
+import { Button, Select } from '@open-design/components';
 import { useT } from '../i18n';
 import type { AgentInfo, ExecMode } from '../types';
 
@@ -27,7 +28,7 @@ export function AgentPicker({
   return (
     <div className="picker agent-picker">
       <span className="picker-label">{t('agentPicker.label')}</span>
-      <select
+      <Select
         value={mode}
         onChange={(e) => onModeChange(e.target.value as ExecMode)}
         title={t('agentPicker.modeChoose')}
@@ -36,10 +37,10 @@ export function AgentPicker({
           {t('agentPicker.localCli')} {daemonLive ? '' : `· ${t('agentPicker.daemonOff')}`}
         </option>
         <option value="api">{t('agentPicker.byok')}</option>
-      </select>
+      </Select>
       {mode === 'daemon' ? (
         <>
-          <select
+          <Select
             value={agentId ?? ''}
             onChange={(e) => onAgentChange(e.target.value)}
             disabled={available.length === 0}
@@ -58,14 +59,14 @@ export function AgentPicker({
                 {a.available ? '' : ` · ${t('agentPicker.notInstalled')}`}
               </option>
             ))}
-          </select>
-          <button
+          </Select>
+          <Button
+            size="icon"
             onClick={onRefresh}
             title={t('agentPicker.rescan')}
-            className="icon-btn"
           >
             ↻
-          </button>
+          </Button>
         </>
       ) : null}
     </div>
diff --git a/apps/web/src/components/BoardComposerPopover.tsx b/apps/web/src/components/BoardComposerPopover.tsx
index bb2bd3451..a231155cc 100644
--- a/apps/web/src/components/BoardComposerPopover.tsx
+++ b/apps/web/src/components/BoardComposerPopover.tsx
@@ -1,4 +1,5 @@
 import { useId } from 'react';
+import { Button, Textarea } from '@open-design/components';
 
 import { selectionKindLabel, type PreviewCommentSnapshot } from '../comments';
 import type { Dict } from '../i18n/types';
@@ -131,14 +132,14 @@ export function BoardComposerPopover({
           {notes.map((note, index) => (
             <div key={`${target.elementId}-${index}`} className="board-note-item">
               <span>{note}</span>
-              <button type="button" className="ghost" onClick={() => onRemoveQueuedNote(index)}>
+              <Button variant="ghost" onClick={() => onRemoveQueuedNote(index)}>
                 {t('chat.comments.remove')}
-              </button>
+              </Button>
             </div>
           ))}
         </div>
       ) : null}
-      <textarea
+      <Textarea
         data-testid="comment-popover-input"
         value={draft}
         autoFocus
@@ -159,35 +160,32 @@ export function BoardComposerPopover({
         ) : null}
         <div className="comment-popover-actions-end">
           {target.selectionKind === 'pod' ? (
-            <button
-              type="button"
-              className="ghost"
+            <Button
+              variant="ghost"
               data-testid="comment-popover-add-note"
               disabled={!draft.trim()}
               onClick={onAddDraft}
             >
               {t('chat.comments.addNote')}
-            </button>
+            </Button>
           ) : (
-            <button
-              type="button"
-              className="ghost"
+            <Button
+              variant="ghost"
               data-testid="comment-popover-save"
               disabled={!draft.trim()}
               onClick={() => void onSaveComment()}
             >
               {t('chat.comments.comment')}
-            </button>
+            </Button>
           )}
-          <button
-            type="button"
-            className="primary"
+          <Button
+            variant="primary"
             data-testid="comment-add-send"
             disabled={pendingCount === 0 || sending}
             onClick={() => void onSendBatch()}
           >
             {sending ? t('chat.comments.sending') : t('chat.comments.sendToChat')}
-          </button>
+          </Button>
         </div>
       </div>
     </div>
diff --git a/apps/web/src/components/ChatComposer.tsx b/apps/web/src/components/ChatComposer.tsx
index e5de8620d..ff132d7cb 100644
--- a/apps/web/src/components/ChatComposer.tsx
+++ b/apps/web/src/components/ChatComposer.tsx
@@ -8,6 +8,7 @@ import {
   useState,
   type ReactNode,
 } from "react";
+import { Button } from '@open-design/components';
 import { useI18n, useT } from '../i18n';
 import type { Dict } from '../i18n/types';
 import {
@@ -1621,8 +1622,8 @@ export const ChatComposer = forwardRef<ChatComposerHandle, Props>(
                 </div>
               ) : null}
             </div>
-            <button
-              className="icon-btn"
+            <Button
+              size="icon"
               data-testid="chat-attach"
               onClick={() => {
                 trackChatPanelClick(analytics.track, {
@@ -1641,7 +1642,7 @@ export const ChatComposer = forwardRef<ChatComposerHandle, Props>(
               ) : (
                 <Icon name="attach" size={15} />
               )}
-            </button>
+            </Button>
             {footerAccessory}
             <span className="composer-spacer" />
             {streaming ? (
diff --git a/apps/web/src/components/ConnectorsBrowser.tsx b/apps/web/src/components/ConnectorsBrowser.tsx
index d02d23ab5..6f179d236 100644
--- a/apps/web/src/components/ConnectorsBrowser.tsx
+++ b/apps/web/src/components/ConnectorsBrowser.tsx
@@ -7,6 +7,7 @@ import {
   type KeyboardEvent as ReactKeyboardEvent,
   type SyntheticEvent,
 } from 'react';
+import { VisuallyHidden } from '@open-design/components';
 import type { ConnectorConnectResponse, ConnectorDetail, ConnectorStatusResponse } from '@open-design/contracts';
 import { useT } from '../i18n';
 import type { Dict } from '../i18n/types';
@@ -900,7 +901,7 @@ export function ConnectorsBrowser({
             >
               <p className="connector-panel-alert-copy" role="status">
                 <strong title={alert.connectorName}>{alert.connectorName}</strong>
-                <span className="sr-only">: </span>
+                <VisuallyHidden>: </VisuallyHidden>
                 <span title={alert.message}>{alert.message}</span>
               </p>
               <button
diff --git a/apps/web/src/components/DesignFilesPanel.tsx b/apps/web/src/components/DesignFilesPanel.tsx
index 30daea6ab..aa42dbf58 100644
--- a/apps/web/src/components/DesignFilesPanel.tsx
+++ b/apps/web/src/components/DesignFilesPanel.tsx
@@ -1,4 +1,5 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
+import { Button } from '@open-design/components';
 import { useAnalytics } from '../analytics/provider';
 import { trackFileManagerClick } from '../analytics/events';
 import { useT } from '../i18n';
@@ -1535,10 +1536,10 @@ function DfPreview({
       </div>
       <div className="df-preview-meta" data-testid="design-file-preview">
         <div className="df-preview-actions">
-          <button type="button" className="ghost" onClick={onOpen}>
+          <Button variant="ghost" onClick={onOpen}>
             <Icon name="eye" size={13} />
             <span>{t('designFiles.previewOpen')}</span>
-          </button>
+          </Button>
           <a
             className="ghost-link"
             href={url}
diff --git a/apps/web/src/components/DesignSystemFlow.tsx b/apps/web/src/components/DesignSystemFlow.tsx
index 29fe19f0f..8f5e178fc 100644
--- a/apps/web/src/components/DesignSystemFlow.tsx
+++ b/apps/web/src/components/DesignSystemFlow.tsx
@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { Button, Textarea } from '@open-design/components';
 import type { ConnectorConnectResponse, ConnectorDetail, ConnectorStatusResponse } from '@open-design/contracts';
 import { streamViaDaemon } from '../providers/daemon';
 import {
@@ -624,19 +625,18 @@ export function DesignSystemCreationFlow({
           <h1>It will take about 5 minutes to generate your design system.</h1>
           <p>You can step away. Keep the tab open in the background.</p>
           <div className="ds-setup-actions">
-            <button type="button" className="ghost" onClick={() => setStep('setup')}>
+            <Button variant="ghost" onClick={() => setStep('setup')}>
               <Icon name="arrow-left" />
               Back
-            </button>
-            <button
-              type="button"
-              className="primary"
+            </Button>
+            <Button
+              variant="primary"
               disabled={generationStarting}
               onClick={() => void generate()}
             >
               <Icon name="sparkles" />
               {generationStarting ? 'Opening project...' : 'Generate'}
-            </button>
+            </Button>
           </div>
         </div>
       </div>
@@ -647,16 +647,15 @@ export function DesignSystemCreationFlow({
     <div className={`ds-setup-shell${embedded ? ' ds-setup-shell--embedded' : ''}`}>
       {embedded ? null : (
         <header className="ds-setup-topbar">
-          <button type="button" className="ghost" onClick={onBack}>
+          <Button variant="ghost" onClick={onBack}>
             <Icon name="arrow-left" />
             Back
-          </button>
+          </Button>
           <span className="ds-setup-mark">
             <Icon name="blocks" />
           </span>
-          <button
-            type="button"
-            className="primary"
+          <Button
+            variant="primary"
             disabled={!state.company.trim()}
             onClick={() => {
               if (!state.company.trim()) {
@@ -668,7 +667,7 @@ export function DesignSystemCreationFlow({
           >
             Continue to generation
             <Icon name="chevron-right" />
-          </button>
+          </Button>
         </header>
       )}
 
@@ -798,7 +797,7 @@ export function DesignSystemCreationFlow({
         {embedded ? null : (
           <label className="ds-setup-field">
             <span>Notes</span>
-            <textarea
+            <Textarea
               rows={4}
               value={state.notes}
               onChange={(event) => setState((curr) => ({ ...curr, notes: event.target.value }))}
@@ -809,13 +808,12 @@ export function DesignSystemCreationFlow({
         {error ? <div className="ds-editor-error">{error}</div> : null}
         {embedded ? (
           <div className="ds-setup-actions ds-setup-actions--embedded">
-            <button type="button" className="ghost" onClick={onBack}>
+            <Button variant="ghost" onClick={onBack}>
               <Icon name="arrow-left" />
               Back
-            </button>
-            <button
-              type="button"
-              className="primary"
+            </Button>
+            <Button
+              variant="primary"
               disabled={!state.company.trim()}
               onClick={() => {
                 if (!state.company.trim()) {
@@ -827,7 +825,7 @@ export function DesignSystemCreationFlow({
             >
               Generate
               <Icon name="chevron-right" />
-            </button>
+            </Button>
           </div>
         ) : null}
       </main>
@@ -1742,10 +1740,10 @@ export function DesignSystemDetailView({
 
       <main className="ds-review-main">
         <header className="ds-review-tabs">
-          <button type="button" className="ghost" onClick={onBack}>
+          <Button variant="ghost" onClick={onBack}>
             <Icon name="arrow-left" />
             Back
-          </button>
+          </Button>
           <div className="segmented">
             <button
               type="button"
@@ -1762,9 +1760,9 @@ export function DesignSystemDetailView({
               Design Files
             </button>
           </div>
-          <button type="button" className="ghost">
+          <Button variant="ghost">
             Share
-          </button>
+          </Button>
         </header>
 
         {tab === 'system' ? (
@@ -1790,9 +1788,9 @@ export function DesignSystemDetailView({
                 Published
               </label>
               {selectedId !== system.id ? (
-                <button
-                  type="button"
-                  className="ghost compact"
+                <Button
+                  variant="ghost"
+                  className="compact"
                   onClick={() => {
                     const statusBefore = mapDsStatusToTracking(system.status);
                     onSetDefault(system.id);
@@ -1812,7 +1810,7 @@ export function DesignSystemDetailView({
                   }}
                 >
                   Make default
-                </button>
+                </Button>
               ) : null}
             </div>
             <DesignSystemPackageCard system={system} />
@@ -1822,10 +1820,10 @@ export function DesignSystemDetailView({
                 <strong>Missing brand fonts</strong>
                 Open Design is rendering typography with substitute web fonts.
               </span>
-              <button type="button" className="ghost compact">
+              <Button variant="ghost" className="compact">
                 <Icon name="upload" />
                 Upload fonts
-              </button>
+              </Button>
             </div>
             {statusLine ? <div className="ds-status-line">{statusLine}</div> : null}
             <WorkspaceActivityCard message={workspaceActivityMessage} active={chatStreaming} />
@@ -1895,16 +1893,16 @@ export function DesignSystemDetailView({
             </div>
             <label className="ds-body-editor">
               DESIGN.md
-              <textarea
+              <Textarea
                 value={body}
                 onChange={(event) => setBody(event.target.value)}
                 rows={16}
                 disabled={!editable}
               />
             </label>
-            <button type="button" className="primary" disabled={!editable || saving} onClick={() => void saveBody()}>
+            <Button variant="primary" disabled={!editable || saving} onClick={() => void saveBody()}>
               Save DESIGN.md
-            </button>
+            </Button>
             {recentRevisions.length > 0 ? <RevisionHistoryList revisions={recentRevisions} /> : null}
           </div>
         ) : (
@@ -2581,9 +2579,9 @@ function DropZone({
           <span>{names.length > 0 && !onRemoveName ? names.join(', ') : prompt}</span>
         </label>
         {onBrowseFolder ? (
-          <button type="button" className="ghost" onClick={onBrowseFolder}>
+          <Button variant="ghost" onClick={onBrowseFolder}>
             Browse folder
-          </button>
+          </Button>
         ) : null}
       </div>
       {names.length > 0 && onRemoveName ? (
@@ -2762,24 +2760,24 @@ function GitHubRepositoryAccessPanel({
   }
 
   const composioAction = !composioConfigured ? (
-    <button type="button" className="ghost" onClick={onOpenConnectorsTab}>
+    <Button variant="ghost" onClick={onOpenConnectorsTab}>
       Configure Composio
-    </button>
+    </Button>
   ) : connected || authorizationPending ? (
     <>
       {authorizationPending && authorizationUrl ? (
-        <button type="button" className="ghost" disabled={busy} onClick={onOpenAuthorization}>
+        <Button variant="ghost" disabled={busy} onClick={onOpenAuthorization}>
           Open authorization
-        </button>
+        </Button>
       ) : null}
-      <button type="button" className="ghost" disabled={busy} onClick={onDisconnect}>
+      <Button variant="ghost" disabled={busy} onClick={onDisconnect}>
         {action === 'disconnect' ? 'Disconnecting...' : 'Disconnect'}
-      </button>
+      </Button>
     </>
   ) : (
-    <button type="button" className="ghost" disabled={busy} onClick={onConnect}>
+    <Button variant="ghost" disabled={busy} onClick={onConnect}>
       {action === 'connect' ? 'Connecting...' : 'Connect via Composio'}
-    </button>
+    </Button>
   );
 
   const methods: GitHubAccessMethod[] = [
diff --git a/apps/web/src/components/DesignSystemsTab.tsx b/apps/web/src/components/DesignSystemsTab.tsx
index 409925125..629959485 100644
--- a/apps/web/src/components/DesignSystemsTab.tsx
+++ b/apps/web/src/components/DesignSystemsTab.tsx
@@ -1,4 +1,5 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
+import { Button } from '@open-design/components';
 import { useAnalytics } from '../analytics/provider';
 import {
   trackDesignSystemsTemplateCardClick,
@@ -455,14 +456,13 @@ export function DesignSystemsTab({
                       <i aria-hidden />
                     </button>
                     {onOpenSystem ? (
-                      <button
-                        type="button"
-                        className="icon-btn"
+                      <Button
+                        size="icon"
                         aria-label={`Open ${system.title}`}
                         onClick={() => onOpenSystem(system.id)}
                       >
                         <Icon name="external-link" />
-                      </button>
+                      </Button>
                     ) : null}
                     <button
                       type="button"
diff --git a/apps/web/src/components/FileViewer.tsx b/apps/web/src/components/FileViewer.tsx
index 143e953a7..d16dbf167 100644
--- a/apps/web/src/components/FileViewer.tsx
+++ b/apps/web/src/components/FileViewer.tsx
@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useId, useMemo, useRef, useState, type CSSProperties, type MouseEvent as ReactMouseEvent, type ReactNode } from 'react';
 import { createPortal } from 'react-dom';
+import { Button, Input, Select } from '@open-design/components';
 import { APP_CHROME_FILE_ACTIONS_ID } from './AppChromeHeader';
 import {
   anonymizeArtifactId,
@@ -2018,18 +2019,17 @@ export function CommentSidePanel({
       {selectedCount > 0 ? (
         <div className="comment-side-selectbar" data-testid="comment-side-selectbar">
           <span className="comment-side-selectcount">{t('chat.comments.nSelected', { n: selectedCount })}</span>
-          <button type="button" className="ghost" onClick={onClearSelection}>
+          <Button variant="ghost" onClick={onClearSelection}>
             {t('chat.comments.clear')}
-          </button>
-          <button
-            type="button"
-            className="primary"
+          </Button>
+          <Button
+            variant="primary"
             data-testid="comment-side-send-claude"
             disabled={sending}
             onClick={() => void onSendSelected()}
           >
             {sending ? t('chat.comments.sending') : t('chat.comments.sendToChat')}
-          </button>
+          </Button>
         </div>
       ) : null}
     </aside>
@@ -2156,9 +2156,9 @@ function InspectPanel({
           <strong title={target.label || target.elementId}>{target.label || target.elementId}</strong>
           <code title={target.selector}>{target.elementId}</code>
         </div>
-        <button type="button" className="ghost" onClick={onClose} aria-label="Close inspect">
+        <Button variant="ghost" onClick={onClose} aria-label="Close inspect">
           ×
-        </button>
+        </Button>
       </header>
 
       {target.clickedDescendant ? (
@@ -2181,14 +2181,14 @@ function InspectPanel({
         <div className="inspect-section-label">Colors</div>
         <div className="inspect-row">
           <label htmlFor="ip-color">Text</label>
-          <input
+          <Input
             id="ip-color"
             data-testid="inspect-color"
             type="color"
             value={colorHex}
             onChange={(e) => setVal('color', e.target.value)}
           />
-          <input
+          <Input
             type="text"
             value={colorHex}
             onChange={(e) => setVal('color', e.target.value)}
@@ -2197,14 +2197,14 @@ function InspectPanel({
         </div>
         <div className="inspect-row">
           <label htmlFor="ip-bg">Background</label>
-          <input
+          <Input
             id="ip-bg"
             data-testid="inspect-bg"
             type="color"
             value={bgHex}
             onChange={(e) => setVal('background-color', e.target.value)}
           />
-          <input
+          <Input
             type="text"
             value={bgHex}
             onChange={(e) => setVal('background-color', e.target.value)}
@@ -2217,7 +2217,7 @@ function InspectPanel({
         <div className="inspect-section-label">Typography</div>
         <div className="inspect-row">
           <label htmlFor="ip-fs">Size</label>
-          <input
+          <Input
             id="ip-fs"
             data-testid="inspect-font-size"
             type="range"
@@ -2231,7 +2231,7 @@ function InspectPanel({
         </div>
         <div className="inspect-row">
           <label htmlFor="ip-fw">Weight</label>
-          <select
+          <Select
             id="ip-fw"
             value={fontWeight}
             onChange={(e) => setVal('font-weight', e.target.value)}
@@ -2239,11 +2239,11 @@ function InspectPanel({
             {['100', '300', '400', '500', '600', '700', '800', '900'].map((w) => (
               <option key={w} value={w}>{w}</option>
             ))}
-          </select>
+          </Select>
         </div>
         <div className="inspect-row">
           <label htmlFor="ip-ta">Align</label>
-          <select
+          <Select
             id="ip-ta"
             value={textAlign}
             onChange={(e) => setVal('text-align', e.target.value)}
@@ -2251,7 +2251,7 @@ function InspectPanel({
             {['left', 'center', 'right', 'justify'].map((a) => (
               <option key={a} value={a}>{a}</option>
             ))}
-          </select>
+          </Select>
         </div>
       </section>
 
@@ -2259,7 +2259,7 @@ function InspectPanel({
         <div className="inspect-section-label">Spacing &amp; Shape</div>
         <div className="inspect-row">
           <label htmlFor="ip-pad">Padding</label>
-          <input
+          <Input
             id="ip-pad"
             data-testid="inspect-padding"
             type="range"
@@ -2273,7 +2273,7 @@ function InspectPanel({
         </div>
         <div className="inspect-row">
           <label htmlFor="ip-rad">Radius</label>
-          <input
+          <Input
             id="ip-rad"
             data-testid="inspect-radius"
             type="range"
@@ -2288,25 +2288,23 @@ function InspectPanel({
       </section>
 
       <footer className="inspect-panel-footer">
-        <button
-          type="button"
-          className="ghost"
+        <Button
+          variant="ghost"
           onClick={() => {
             setDraft({});
             onResetElement(target.elementId);
           }}
         >
           Reset element
-        </button>
-        <button
-          type="button"
-          className="primary"
+        </Button>
+        <Button
+          variant="primary"
           data-testid="inspect-save"
           disabled={saving}
           onClick={onSaveToSource}
         >
           {saving ? 'Saving…' : justSaved ? 'Saved ✓' : 'Save to source'}
-        </button>
+        </Button>
       </footer>
       {error ? <div className="inspect-panel-error">{error}</div> : null}
     </aside>
diff --git a/apps/web/src/components/FileWorkspace.tsx b/apps/web/src/components/FileWorkspace.tsx
index e302e1011..f528ea5d8 100644
--- a/apps/web/src/components/FileWorkspace.tsx
+++ b/apps/web/src/components/FileWorkspace.tsx
@@ -5,6 +5,7 @@ import {
   useState,
   type DragEvent as ReactDragEvent,
 } from 'react';
+import { Button } from '@open-design/components';
 import type { TrackingProjectKind } from '@open-design/contracts/analytics';
 import { useAnalytics } from '../analytics/provider';
 import {
@@ -1557,14 +1558,14 @@ function DesignSystemProjectPanel({
           {published ? (
             <div className="ds-project-use-row">
               <span>Use this system</span>
-              <button
-                type="button"
-                className="ghost compact"
+              <Button
+                variant="ghost"
+                className="compact"
                 onClick={() => onUseDesignSystem?.(system.id, system.title)}
               >
                 <Icon name="external-link" size={13} />
                 New design
-              </button>
+              </Button>
             </div>
           ) : null}
         </div>
@@ -1577,20 +1578,20 @@ function DesignSystemProjectPanel({
               <small>{repoConnectCopy(githubConnected).bannerBody}</small>
             </span>
             {onConnectRepo ? (
-              <button
-                type="button"
-                className="ghost compact"
+              <Button
+                variant="ghost"
+                className="compact"
                 disabled={githubConnected === undefined}
                 onClick={onConnectRepo}
               >
                 <Icon name="github" size={13} />
                 {repoConnectCopy(githubConnected).buttonLabel}
-              </button>
+              </Button>
             ) : githubEvidence.hasSourceManifest ? (
-              <button type="button" className="ghost compact" onClick={() => onOpenFile('context/source-context.md')}>
+              <Button variant="ghost" className="compact" onClick={() => onOpenFile('context/source-context.md')}>
                 <Icon name="file" size={13} />
                 Open source context
-              </button>
+              </Button>
             ) : null}
           </div>
         ) : null}
diff --git a/apps/web/src/components/McpClientSection.tsx b/apps/web/src/components/McpClientSection.tsx
index 79de79375..d8e91392c 100644
--- a/apps/web/src/components/McpClientSection.tsx
+++ b/apps/web/src/components/McpClientSection.tsx
@@ -13,6 +13,7 @@ import {
   useRef,
   useState,
 } from 'react';
+import { Button, Input } from '@open-design/components';
 import { useAnalytics } from '../analytics/provider';
 import { trackIntegrationsMcpTabClick } from '../analytics/events';
 import {
@@ -752,7 +753,7 @@ function McpRow({ row, idx, total, template, onChange, onRemove, onMoveUp, onMov
           />
         </label>
         {expanded ? (
-          <input
+          <Input
             type="text"
             className="mcp-row-label"
             value={row.label ?? ''}
@@ -780,33 +781,32 @@ function McpRow({ row, idx, total, template, onChange, onRemove, onMoveUp, onMov
         </span>
         <div className="mcp-row-actions">
           {onMoveUp ? (
-            <button type="button" className="icon-btn" onClick={onMoveUp} title="Move up">
+            <Button size="icon" onClick={onMoveUp} title="Move up">
               ↑
-            </button>
+            </Button>
           ) : null}
           {onMoveDown ? (
-            <button type="button" className="icon-btn" onClick={onMoveDown} title="Move down">
+            <Button size="icon" onClick={onMoveDown} title="Move down">
               ↓
-            </button>
+            </Button>
           ) : null}
-          <button
-            type="button"
-            className="icon-btn"
+          <Button
+            size="icon"
             onClick={onRemove}
             title="Remove this MCP server"
           >
             ×
-          </button>
-          <button
-            type="button"
-            className="icon-btn mcp-row-toggle-btn"
+          </Button>
+          <Button
+            size="icon"
+            className="mcp-row-toggle-btn"
             onClick={() => setExpanded((v) => !v)}
             aria-expanded={expanded}
             aria-label={expanded ? 'Collapse this MCP server' : 'Expand this MCP server'}
             title={expanded ? 'Collapse' : 'Expand'}
           >
             <Icon name="chevron-down" size={13} />
-          </button>
+          </Button>
         </div>
       </div>
 
diff --git a/apps/web/src/components/MemorySection.tsx b/apps/web/src/components/MemorySection.tsx
index 5284a439b..673889fdf 100644
--- a/apps/web/src/components/MemorySection.tsx
+++ b/apps/web/src/components/MemorySection.tsx
@@ -6,6 +6,7 @@ import {
   useState,
   type CSSProperties,
 } from 'react';
+import { Button } from '@open-design/components';
 import { Icon, type IconName } from './Icon';
 import { ConnectorLogo, useResolvedTheme } from './ConnectorLogo';
 import { useT } from '../i18n';
@@ -1833,17 +1834,16 @@ export function MemorySection({
                   {t('settings.memorySaveHint')}
                 </span>
                 <div style={{ display: 'flex', gap: 8 }}>
-                  <button type="button" className="ghost" onClick={cancelEdit}>
+                  <Button variant="ghost" onClick={cancelEdit}>
                     {t('common.cancel')}
-                  </button>
-                  <button
-                    type="button"
-                    className="primary"
+                  </Button>
+                  <Button
+                    variant="primary"
                     onClick={onSave}
                     disabled={busy || !editing.name.trim()}
                   >
                     {editing.id ? t('common.save') : t('common.create')}
-                  </button>
+                  </Button>
                 </div>
               </div>
             </div>
diff --git a/apps/web/src/components/MissingBrandFontsBanner.tsx b/apps/web/src/components/MissingBrandFontsBanner.tsx
index 6f6601804..e1e85c5fa 100644
--- a/apps/web/src/components/MissingBrandFontsBanner.tsx
+++ b/apps/web/src/components/MissingBrandFontsBanner.tsx
@@ -1,4 +1,5 @@
 import { useEffect, useState } from 'react';
+import { Button } from '@open-design/components';
 
 import { Icon } from './Icon';
 
@@ -69,14 +70,14 @@ export function MissingBrandFontsBanner({
       </span>
       <div className="ds-warning-card-actions">
         {onUploadAssets ? (
-          <button type="button" className="ghost compact" onClick={onUploadAssets}>
+          <Button variant="ghost" className="compact" onClick={onUploadAssets}>
             <Icon name="upload" size={13} />
             Upload fonts
-          </button>
+          </Button>
         ) : null}
-        <button type="button" className="ghost compact" onClick={useSystemFonts}>
+        <Button variant="ghost" className="compact" onClick={useSystemFonts}>
           Use system fonts
-        </button>
+        </Button>
       </div>
     </div>
   );
diff --git a/apps/web/src/components/PasteTextDialog.tsx b/apps/web/src/components/PasteTextDialog.tsx
index 03f5d5ce9..13defce17 100644
--- a/apps/web/src/components/PasteTextDialog.tsx
+++ b/apps/web/src/components/PasteTextDialog.tsx
@@ -1,4 +1,5 @@
 import { useState } from 'react';
+import { Button, Input, Textarea } from '@open-design/components';
 import { useT } from '../i18n';
 
 interface Props {
@@ -25,7 +26,7 @@ export function PasteTextDialog({ onSave, onClose }: Props) {
         <p className="hint">{t('pasteDialog.hint')}</p>
         <label>
           {t('pasteDialog.fileNameLabel')}
-          <input
+          <Input
             type="text"
             value={name}
             placeholder={t('pasteDialog.namePlaceholder')}
@@ -35,7 +36,7 @@ export function PasteTextDialog({ onSave, onClose }: Props) {
         </label>
         <label>
           {t('pasteDialog.contentLabel')}
-          <textarea
+          <Textarea
             rows={10}
             value={content}
             placeholder={t('pasteDialog.contentPlaceholder')}
@@ -43,10 +44,10 @@ export function PasteTextDialog({ onSave, onClose }: Props) {
           />
         </label>
         <div className="row">
-          <button onClick={onClose}>{t('pasteDialog.cancel')}</button>
-          <button className="primary" onClick={commit} disabled={!content.trim()}>
+          <Button onClick={onClose}>{t('pasteDialog.cancel')}</Button>
+          <Button variant="primary" onClick={commit} disabled={!content.trim()}>
             {t('pasteDialog.save')}
-          </button>
+          </Button>
         </div>
       </div>
     </div>
diff --git a/apps/web/src/components/SettingsDialog.tsx b/apps/web/src/components/SettingsDialog.tsx
index 95524a78b..b031798aa 100644
--- a/apps/web/src/components/SettingsDialog.tsx
+++ b/apps/web/src/components/SettingsDialog.tsx
@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import type { CSSProperties, Dispatch, SetStateAction } from 'react';
+import { Button, VisuallyHidden } from '@open-design/components';
 import { validateBaseUrl } from '@open-design/contracts/api/connectionTest';
 import {
   agentIdToTracking,
@@ -4944,9 +4945,9 @@ function MediaProvidersSection({
         // Off-screen announcement so assistive tech still hears the
         // success state even though the visible feedback collapses
         // into a transient button label change.
-        <span className="sr-only" role="status">
+        <VisuallyHidden role="status">
           {reloadNotice.message}
-        </span>
+        </VisuallyHidden>
       ) : null}
       {onReloadMediaProviders ? (
         <div className="media-provider-reload-row">
@@ -6130,7 +6131,7 @@ function NotificationsSection({
         ) : null}
         {notif.desktopEnabled && permission === 'granted' ? (
           <>
-            <button type="button" className="ghost" onClick={() => {
+            <Button variant="ghost" onClick={() => {
               trackSettingsNotificationsClick(analytics.track, {
                 page_name: 'settings',
                 area: 'notifications',
@@ -6139,7 +6140,7 @@ function NotificationsSection({
               void sendTestNotification();
             }}>
               {t('settings.notifyTest')}
-            </button>
+            </Button>
             {testStatus ? <p className="hint" role="status">{t(testStatus)}</p> : null}
           </>
         ) : null}
diff --git a/apps/web/src/components/SketchEditor.tsx b/apps/web/src/components/SketchEditor.tsx
index 516e1a772..4412e32ad 100644
--- a/apps/web/src/components/SketchEditor.tsx
+++ b/apps/web/src/components/SketchEditor.tsx
@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
+import { Button, Input } from '@open-design/components';
 import { useT } from '../i18n';
 import { Icon } from './Icon';
 import { readDefaultSketchToolColor } from './sketch-colors';
@@ -245,30 +246,30 @@ export function SketchEditor({
           className="sketch-size"
         />
         <span className="sketch-divider" />
-        <button className="ghost" onClick={handleUndo} disabled={items.length === 0}>
+        <Button variant="ghost" onClick={handleUndo} disabled={items.length === 0}>
           {t('sketch.undo')}
-        </button>
-        <button className="ghost" onClick={handleClear} disabled={!canClear}>
+        </Button>
+        <Button variant="ghost" onClick={handleClear} disabled={!canClear}>
           {t('sketch.clear')}
-        </button>
+        </Button>
         <span className="sketch-spacer" />
         <span className="sketch-name" title={fileName}>
           {fileName}
           {dirty ? ' •' : ''}
         </span>
         {onCancel ? (
-          <button className="ghost" onClick={onCancel}>
+          <Button variant="ghost" onClick={onCancel}>
             {t('sketch.close')}
-          </button>
+          </Button>
         ) : null}
-        <button
-          className="primary"
+        <Button
+          variant="primary"
           onClick={handleSave}
           disabled={saving || !canSave}
           aria-label={saving ? t('sketch.saving') : showSaved ? t('sketch.saved') : t('common.save')}
         >
           {saving ? t('sketch.saving') : showSaved ? <Icon name="check" size={14} /> : t('common.save')}
-        </button>
+        </Button>
       </div>
       <div className="sketch-canvas-wrap" ref={wrapRef}>
         <canvas
@@ -288,7 +289,7 @@ export function SketchEditor({
             </div>
             <label>
               <span>{t('sketch.textPrompt')}</span>
-              <input
+              <Input
                 type="text"
                 value={textModalValue}
                 autoFocus
@@ -305,17 +306,16 @@ export function SketchEditor({
               />
             </label>
             <div className="modal-foot">
-              <button type="button" className="ghost" onClick={cancelTextModal}>
+              <Button variant="ghost" onClick={cancelTextModal}>
                 {t('common.cancel')}
-              </button>
-              <button
-                type="button"
-                className="primary"
+              </Button>
+              <Button
+                variant="primary"
                 disabled={!textModalValue.trim()}
                 onClick={submitTextModal}
               >
                 {t('common.save')}
-              </button>
+              </Button>
             </div>
           </div>
         </div>
diff --git a/apps/web/src/components/SkillsSection.tsx b/apps/web/src/components/SkillsSection.tsx
index 0c1fb73c5..233eeb1bc 100644
--- a/apps/web/src/components/SkillsSection.tsx
+++ b/apps/web/src/components/SkillsSection.tsx
@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import type { Dispatch, SetStateAction } from 'react';
+import { Button } from '@open-design/components';
 import { useI18n, useT } from '../i18n';
 import {
   localizeSkillDescription,
@@ -634,25 +635,23 @@ function SkillRow({
             </span>
           ) : (
             <>
-              <button
-                type="button"
-                className="icon-btn"
+              <Button
+                size="icon"
                 onClick={onStartEdit}
                 title={t('settings.skillsEdit')}
                 data-testid="skills-edit"
               >
                 <Icon name="edit" size={13} />
-              </button>
+              </Button>
               {canDelete ? (
-                <button
-                  type="button"
-                  className="icon-btn"
+                <Button
+                  size="icon"
                   onClick={onArmDelete}
                   title={t('settings.skillsDelete')}
                   data-testid="skills-delete"
                 >
                   <Icon name="close" size={13} />
-                </button>
+                </Button>
               ) : null}
             </>
           )}
diff --git a/apps/web/src/components/plugins-home/PluginCard.tsx b/apps/web/src/components/plugins-home/PluginCard.tsx
index 6fda5e791..d4b1a01d0 100644
--- a/apps/web/src/components/plugins-home/PluginCard.tsx
+++ b/apps/web/src/components/plugins-home/PluginCard.tsx
@@ -13,6 +13,7 @@
 // needs to commit.
 
 import { useMemo, useState } from 'react';
+import { VisuallyHidden } from '@open-design/components';
 import type { InstalledPluginRecord } from '@open-design/contracts';
 import { useI18n } from '../../i18n';
 import type { PluginShareAction } from '../../state/projects';
@@ -261,7 +262,7 @@ export function PluginCard({
           data-testid={`plugins-home-save-${record.id}`}
         >
           <Icon name={isSaved ? 'check' : 'star'} size={12} />
-          <span className="sr-only">{isSaved ? 'Saved' : 'Save'}</span>
+          <VisuallyHidden>{isSaved ? 'Saved' : 'Save'}</VisuallyHidden>
         </button>
         <span className="plugins-home__card-title" title={title}>
           <span className="plugins-home__card-title-text">{title}</span>
diff --git a/packages/components/src/button.tsx b/packages/components/src/button.tsx
index 6f938e581..7cfbf9c23 100644
--- a/packages/components/src/button.tsx
+++ b/packages/components/src/button.tsx
@@ -1,7 +1,7 @@
 import { forwardRef } from 'react';
 import type { ButtonHTMLAttributes } from 'react';
 
-import { joinClassNames } from './class-names.js';
+import { joinClassNames } from './class-names';
 import styles from './button.module.css';
 
 export type ButtonVariant = 'default' | 'primary' | 'primary-ghost' | 'ghost' | 'subtle';
@@ -14,15 +14,15 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
 
 const variantClassNames: Record<ButtonVariant, string | undefined> = {
   default: undefined,
-  primary: styles.primary,
-  'primary-ghost': styles.primaryGhost,
-  ghost: styles.ghost,
-  subtle: styles.subtle,
+  primary: joinClassNames(styles.primary, 'primary'),
+  'primary-ghost': joinClassNames(styles.primaryGhost, 'primary-ghost'),
+  ghost: joinClassNames(styles.ghost, 'ghost'),
+  subtle: joinClassNames(styles.subtle, 'subtle'),
 };
 
 const sizeClassNames: Record<ButtonSize, string | undefined> = {
   default: undefined,
-  icon: styles.icon,
+  icon: joinClassNames(styles.icon, 'icon-btn'),
 };
 
 export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
diff --git a/packages/components/src/form-controls.module.css b/packages/components/src/form-controls.module.css
new file mode 100644
index 000000000..dc4141a65
--- /dev/null
+++ b/packages/components/src/form-controls.module.css
@@ -0,0 +1,49 @@
+.control {
+  font: inherit;
+  color: var(--text);
+  background: var(--bg-panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 7px 10px;
+  width: 100%;
+  transition: border-color 120ms ease, box-shadow 120ms ease;
+}
+
+.control::placeholder {
+  color: var(--text-faint);
+}
+
+.control:focus {
+  outline: none;
+  border-color: var(--selected);
+  box-shadow: 0 0 0 3px var(--selected-soft);
+}
+
+.textarea {
+  resize: vertical;
+  font-family: inherit;
+}
+
+.select {
+  padding-right: 32px;
+  appearance: none;
+  -webkit-appearance: none;
+  background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' fill='none' stroke='%2374716b' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='3 5 6 8 9 5'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 10px center;
+  background-size: 12px 12px;
+}
+
+.select::-ms-expand {
+  display: none;
+}
+
+[data-theme='dark'] .select {
+  background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' fill='none' stroke='%239a9690' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='3 5 6 8 9 5'/%3E%3C/svg%3E");
+}
+
+@media (prefers-color-scheme: dark) {
+  html:not([data-theme]) .select {
+    background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12' fill='none' stroke='%239a9690' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='3 5 6 8 9 5'/%3E%3C/svg%3E");
+  }
+}
diff --git a/packages/components/src/form-controls.tsx b/packages/components/src/form-controls.tsx
new file mode 100644
index 000000000..4e7cdcd37
--- /dev/null
+++ b/packages/components/src/form-controls.tsx
@@ -0,0 +1,32 @@
+import { forwardRef } from 'react';
+import type { InputHTMLAttributes, SelectHTMLAttributes, TextareaHTMLAttributes } from 'react';
+
+import { joinClassNames } from './class-names';
+import styles from './form-controls.module.css';
+
+export type InputProps = InputHTMLAttributes<HTMLInputElement>;
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
+  { className, ...props },
+  ref,
+) {
+  return <input ref={ref} className={joinClassNames(styles.control, className)} {...props} />;
+});
+
+export type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement>;
+
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function Textarea(
+  { className, ...props },
+  ref,
+) {
+  return <textarea ref={ref} className={joinClassNames(styles.control, styles.textarea, className)} {...props} />;
+});
+
+export type SelectProps = SelectHTMLAttributes<HTMLSelectElement>;
+
+export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select(
+  { className, ...props },
+  ref,
+) {
+  return <select ref={ref} className={joinClassNames(styles.control, styles.select, className)} {...props} />;
+});
diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
index 68782c381..a93db12d0 100644
--- a/packages/components/src/index.ts
+++ b/packages/components/src/index.ts
@@ -1,4 +1,6 @@
-export { Button } from './button.js';
-export type { ButtonProps, ButtonSize, ButtonVariant } from './button.js';
-export { VisuallyHidden } from './visually-hidden.js';
-export type { VisuallyHiddenProps } from './visually-hidden.js';
+export { Button } from './button';
+export type { ButtonProps, ButtonSize, ButtonVariant } from './button';
+export { Input, Select, Textarea } from './form-controls';
+export type { InputProps, SelectProps, TextareaProps } from './form-controls';
+export { VisuallyHidden } from './visually-hidden';
+export type { VisuallyHiddenProps } from './visually-hidden';
diff --git a/packages/components/src/primitives.tsx b/packages/components/src/primitives.tsx
index 68782c381..a93db12d0 100644
--- a/packages/components/src/primitives.tsx
+++ b/packages/components/src/primitives.tsx
@@ -1,4 +1,6 @@
-export { Button } from './button.js';
-export type { ButtonProps, ButtonSize, ButtonVariant } from './button.js';
-export { VisuallyHidden } from './visually-hidden.js';
-export type { VisuallyHiddenProps } from './visually-hidden.js';
+export { Button } from './button';
+export type { ButtonProps, ButtonSize, ButtonVariant } from './button';
+export { Input, Select, Textarea } from './form-controls';
+export type { InputProps, SelectProps, TextareaProps } from './form-controls';
+export { VisuallyHidden } from './visually-hidden';
+export type { VisuallyHiddenProps } from './visually-hidden';
diff --git a/packages/components/src/visually-hidden.tsx b/packages/components/src/visually-hidden.tsx
index 640881e53..c1a014764 100644
--- a/packages/components/src/visually-hidden.tsx
+++ b/packages/components/src/visually-hidden.tsx
@@ -1,13 +1,12 @@
-import type { ReactNode } from 'react';
+import type { HTMLAttributes, ReactNode } from 'react';
 
-import { joinClassNames } from './class-names.js';
+import { joinClassNames } from './class-names';
 import styles from './visually-hidden.module.css';
 
-export interface VisuallyHiddenProps {
+export interface VisuallyHiddenProps extends HTMLAttributes<HTMLSpanElement> {
   children: ReactNode;
-  className?: string;
 }
 
-export function VisuallyHidden({ children, className }: VisuallyHiddenProps) {
-  return <span className={joinClassNames(styles.visuallyHidden, className)}>{children}</span>;
+export function VisuallyHidden({ children, className, ...props }: VisuallyHiddenProps) {
+  return <span className={joinClassNames(styles.visuallyHidden, className)} {...props}>{children}</span>;
 }

From c2caeda75bcebb6b0a72450409a2f084326ae93e Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Mon, 25 May 2026 23:02:17 +0800
Subject: [PATCH 09/22] fix(web): preserve migrated control styling

---
 apps/web/src/components/FileViewer.tsx  | 6 +++---
 apps/web/src/styles/viewer/composio.css | 4 ++--
 apps/web/src/styles/viewer/core.css     | 7 +++++--
 3 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/components/FileViewer.tsx b/apps/web/src/components/FileViewer.tsx
index d16dbf167..42ca373c4 100644
--- a/apps/web/src/components/FileViewer.tsx
+++ b/apps/web/src/components/FileViewer.tsx
@@ -2217,7 +2217,7 @@ function InspectPanel({
         <div className="inspect-section-label">Typography</div>
         <div className="inspect-row">
           <label htmlFor="ip-fs">Size</label>
-          <Input
+          <input
             id="ip-fs"
             data-testid="inspect-font-size"
             type="range"
@@ -2259,7 +2259,7 @@ function InspectPanel({
         <div className="inspect-section-label">Spacing &amp; Shape</div>
         <div className="inspect-row">
           <label htmlFor="ip-pad">Padding</label>
-          <Input
+          <input
             id="ip-pad"
             data-testid="inspect-padding"
             type="range"
@@ -2273,7 +2273,7 @@ function InspectPanel({
         </div>
         <div className="inspect-row">
           <label htmlFor="ip-rad">Radius</label>
-          <Input
+          <input
             id="ip-rad"
             data-testid="inspect-radius"
             type="range"
diff --git a/apps/web/src/styles/viewer/composio.css b/apps/web/src/styles/viewer/composio.css
index e5706696d..020351e3e 100644
--- a/apps/web/src/styles/viewer/composio.css
+++ b/apps/web/src/styles/viewer/composio.css
@@ -357,8 +357,8 @@
 }
 .picker select {
   border: none;
-  background: transparent;
-  padding: 4px 6px;
+  background-color: transparent;
+  padding: 4px 26px 4px 6px;
   width: auto;
   min-width: 120px;
   box-shadow: none;
diff --git a/apps/web/src/styles/viewer/core.css b/apps/web/src/styles/viewer/core.css
index b7869a1a7..0e7a76433 100644
--- a/apps/web/src/styles/viewer/core.css
+++ b/apps/web/src/styles/viewer/core.css
@@ -1577,13 +1577,16 @@ button.ghost.mcp-copy-btn:hover:not(:disabled) {
 .inspect-row input[type='text'],
 .inspect-row select {
   min-width: 0;
-  padding: 3px 6px;
+  padding: 3px 26px 3px 6px;
   border: 1px solid var(--border);
   border-radius: 4px;
-  background: var(--bg);
+  background-color: var(--bg);
   font-size: 11px;
   font-family: inherit;
 }
+.inspect-row input[type='text'] {
+  padding-right: 6px;
+}
 .inspect-row input[type='range'] {
   width: 100%;
 }

From bce76d69afc6cd20d3e79f9da09bd80ac14be79e Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Tue, 26 May 2026 11:53:44 +0800
Subject: [PATCH 10/22] fix(nix): refresh daemon pnpm deps hash

Generated-By: looper 0.9.1 (runner=fixer, agent=opencode)
---
 nix/pnpm-deps.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nix/pnpm-deps.nix b/nix/pnpm-deps.nix
index 97d3b754d..0fcc103c3 100644
--- a/nix/pnpm-deps.nix
+++ b/nix/pnpm-deps.nix
@@ -8,6 +8,6 @@
   # 1. Temporarily set the consuming `hash = lib.fakeHash;`
   # 2. Run the relevant nix build/flake check
   # 3. Copy the expected hash printed by Nix into the matching field below
-  daemonHash = "sha256-tqxFDNPQjoKUWp4sLtPVCUu7ltIL/ufeyr6UKOWYw6A=";
+  daemonHash = "sha256-p8D5OmvQ/4FuIYK6BnysLxW99dEZoxfr0Zm2xlkfCdU=";
   webHash = "sha256-74loUCL+WcaZO4AAMnSpNeBhDz1Y9TMgFRPbyaOfPAk=";
 }

From e12a9a09ac530417d00cbad5064500a4b1242b01 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Tue, 26 May 2026 12:03:52 +0800
Subject: [PATCH 11/22] fix(web): keep Continue in CLI action styling

Generated-By: looper 0.9.1 (runner=fixer, agent=opencode)
---
 apps/web/src/components/ContinueInCliButton.tsx | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/apps/web/src/components/ContinueInCliButton.tsx b/apps/web/src/components/ContinueInCliButton.tsx
index fd2074529..7a557ac33 100644
--- a/apps/web/src/components/ContinueInCliButton.tsx
+++ b/apps/web/src/components/ContinueInCliButton.tsx
@@ -17,7 +17,6 @@
 // component itself.
 
 import type { DesignMdState, DesignMdStaleReason } from '../hooks/useDesignMdState';
-import { Button } from '@open-design/components';
 
 const STALE_CHIP_TEXT = 'Spec is stale — regenerate?';
 // Round 7 (mrcfps @ useDesignMdState.ts:160): malformed provenance
@@ -47,13 +46,14 @@ export function ContinueInCliButton({ designMdState, onClick }: ContinueInCliBut
     // explanation when the disabled button gets focused.
     return (
       <span className="project-actions-button-group">
-        <Button
+        <button
+          type="button"
           className="project-actions-button project-actions-button-secondary"
           disabled
           aria-describedby="continue-in-cli-disabled-hint"
         >
           Continue in CLI
-        </Button>
+        </button>
         <span
           id="continue-in-cli-disabled-hint"
           className="project-actions-disabled-hint"
@@ -67,14 +67,15 @@ export function ContinueInCliButton({ designMdState, onClick }: ContinueInCliBut
 
   return (
     <span className="project-actions-button-group">
-      <Button
+      <button
+        type="button"
         className="project-actions-button project-actions-button-secondary"
         onClick={() => {
           void onClick();
         }}
       >
         Continue in CLI
-      </Button>
+      </button>
       {designMdState.isStale ? (
         <span className="project-actions-chip" role="note" aria-label="Spec staleness">
           {chipTextForReason(designMdState.staleReason)}

From dc58b369973dbdeb0fb7efdd4b0c65fc5f1842bb Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Tue, 26 May 2026 12:16:13 +0800
Subject: [PATCH 12/22] fix(web): keep finalize action styling

Generated-By: looper 0.9.1 (runner=fixer, agent=opencode)
---
 apps/web/src/components/FinalizeDesignButton.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/apps/web/src/components/FinalizeDesignButton.tsx b/apps/web/src/components/FinalizeDesignButton.tsx
index 548179046..2ea8cba4c 100644
--- a/apps/web/src/components/FinalizeDesignButton.tsx
+++ b/apps/web/src/components/FinalizeDesignButton.tsx
@@ -12,7 +12,6 @@
 
 import type { DesignMdState } from '../hooks/useDesignMdState';
 import type { FinalizeStatus } from '../hooks/useFinalizeProject';
-import { Button } from '@open-design/components';
 
 export interface FinalizeDesignButtonProps {
   designMdState: Pick<DesignMdState, 'exists' | 'isStale'>;
@@ -58,11 +57,12 @@ export function FinalizeDesignButton({
   }
 
   return (
-    <Button
+    <button
+      type="button"
       className={`project-actions-button ${variantClass}`}
       onClick={onFinalize}
     >
       {label}
-    </Button>
+    </button>
   );
 }

From e53c13b25ca7b3bbbf7dc9ffbb0d09eb9c030ed6 Mon Sep 17 00:00:00 2001
From: "open-design-bot[bot]"
 <282769551+open-design-bot[bot]@users.noreply.github.com>
Date: Tue, 26 May 2026 08:08:48 +0000
Subject: [PATCH 13/22] chore(nix): refresh pnpm deps hash

---
 nix/pnpm-deps.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nix/pnpm-deps.nix b/nix/pnpm-deps.nix
index e1062a5c1..daea7e98b 100644
--- a/nix/pnpm-deps.nix
+++ b/nix/pnpm-deps.nix
@@ -9,6 +9,6 @@
   # 1. Temporarily set the consuming `hash = lib.fakeHash;`
   # 2. Run the relevant nix build/flake check
   # 3. Copy the expected hash printed by Nix into the matching field below
-  daemonHash = "sha256-p8D5OmvQ/4FuIYK6BnysLxW99dEZoxfr0Zm2xlkfCdU=";
+  daemonHash = "sha256-tqxFDNPQjoKUWp4sLtPVCUu7ltIL/ufeyr6UKOWYw6A=";
   webHash = "sha256-74loUCL+WcaZO4AAMnSpNeBhDz1Y9TMgFRPbyaOfPAk=";
 }

From e71f20fda14848acf3fc7d136aed20cf1446a1b3 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Tue, 26 May 2026 18:58:32 +0800
Subject: [PATCH 14/22] fix(web): preserve MCP row label styling

Generated-By: looper 0.9.1 (runner=fixer, agent=opencode)
---
 apps/web/src/components/McpClientSection.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/McpClientSection.tsx b/apps/web/src/components/McpClientSection.tsx
index d8e91392c..64d5d4543 100644
--- a/apps/web/src/components/McpClientSection.tsx
+++ b/apps/web/src/components/McpClientSection.tsx
@@ -13,7 +13,7 @@ import {
   useRef,
   useState,
 } from 'react';
-import { Button, Input } from '@open-design/components';
+import { Button } from '@open-design/components';
 import { useAnalytics } from '../analytics/provider';
 import { trackIntegrationsMcpTabClick } from '../analytics/events';
 import {
@@ -753,7 +753,7 @@ function McpRow({ row, idx, total, template, onChange, onRemove, onMoveUp, onMov
           />
         </label>
         {expanded ? (
-          <Input
+          <input
             type="text"
             className="mcp-row-label"
             value={row.label ?? ''}

From 51f0f1f49e42dd50a3ef034f2cbe1aa1496a58f9 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Thu, 28 May 2026 16:44:00 +0800
Subject: [PATCH 15/22] fix(web): resolve ChatComposer merge conflict

Generated-By: looper 0.9.2 (runner=fixer, agent=opencode)
---
 apps/web/src/components/ChatComposer.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/apps/web/src/components/ChatComposer.tsx b/apps/web/src/components/ChatComposer.tsx
index c96c397d9..eb404fe0f 100644
--- a/apps/web/src/components/ChatComposer.tsx
+++ b/apps/web/src/components/ChatComposer.tsx
@@ -8,6 +8,7 @@ import {
   useState,
   type ReactNode,
 } from "react";
+import { createPortal } from 'react-dom';
 import { Button } from '@open-design/components';
 import { useI18n, useT } from '../i18n';
 import type { Dict } from '../i18n/types';

From 17bd8f0e5743bfcad38a2deb1033b3c52f46ca6f Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Thu, 28 May 2026 16:54:05 +0800
Subject: [PATCH 16/22] fix(e2e): stop leaked tools-dev runtime before retry

Generated-By: looper 0.9.2 (runner=fixer, agent=opencode)
---
 e2e/lib/vitest/smoke-suite.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/e2e/lib/vitest/smoke-suite.ts b/e2e/lib/vitest/smoke-suite.ts
index f6b2a1daa..37f55e34a 100644
--- a/e2e/lib/vitest/smoke-suite.ts
+++ b/e2e/lib/vitest/smoke-suite.ts
@@ -142,6 +142,7 @@ async function runToolsDevSuite(
         break;
       } catch (error) {
         if (attempt === 3 || !toolsDev.isToolsDevPortConflict(error)) throw error;
+        await toolsDev.stopToolsDevWeb(suite).catch(() => undefined);
         runtime = await toolsDev.allocateToolsDevRuntime();
       }
     }

From 2773619d464694345579255a215feaf7ce382da6 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Fri, 29 May 2026 17:10:11 +0800
Subject: [PATCH 17/22] ci: include packages/components in change scopes

Generated-By: looper 0.9.2 (runner=fixer, agent=opencode)
---
 .github/workflows/ci.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c56ed31f7..3715a66d0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -61,7 +61,7 @@ jobs:
               if [[ "$file" == "apps/daemon/"* || "$file" == "packages/contracts/"* || "$file" == "packages/platform/"* || "$file" == "packages/sidecar/"* || "$file" == "packages/sidecar-proto/"* ]]; then
                 daemon_tests_required=true
               fi
-              if [[ "$file" == "apps/web/"* || "$file" == "packages/contracts/"* || "$file" == "packages/host/"* || "$file" == "packages/platform/"* || "$file" == "packages/sidecar/"* || "$file" == "packages/sidecar-proto/"* ]]; then
+              if [[ "$file" == "apps/web/"* || "$file" == "packages/components/"* || "$file" == "packages/contracts/"* || "$file" == "packages/host/"* || "$file" == "packages/platform/"* || "$file" == "packages/sidecar/"* || "$file" == "packages/sidecar-proto/"* ]]; then
                 web_tests_required=true
               fi
               if [[ "$file" == "scripts/"* || "$file" == "assets/"* || "$file" == "skills/"* || "$file" == "prompt-templates/"* || "$file" == "design-systems/"* || "$file" == "design-templates/"* || "$file" == "craft/"* ]]; then
@@ -81,7 +81,7 @@ jobs:
                 tools_pack_tests_required=true
               fi
               # Keep this filter in sync with flake.nix daemonWorkspacePaths / webWorkspacePaths.
-              if [[ "$file" == "package.json" || "$file" == "pnpm-lock.yaml" || "$file" == "pnpm-workspace.yaml" || "$file" == "flake.nix" || "$file" == "flake.lock" || "$file" == "nix/"* || "$file" == ".github/workflows/ci.yml" || "$file" == ".github/workflows/nix-check.yml" || "$file" == ".github/workflows/nix-hash-autofix.yml" || "$file" == "apps/daemon/"* || "$file" == "apps/web/"* || "$file" == "packages/contracts/"* || "$file" == "packages/registry-protocol/"* || "$file" == "packages/agui-adapter/"* || "$file" == "packages/plugin-runtime/"* || "$file" == "packages/sidecar-proto/"* || "$file" == "packages/sidecar/"* || "$file" == "packages/platform/"* || "$file" == "packages/diagnostics/"* || "$file" == "packages/host/"* || "$file" == "assets/"* || "$file" == "plugins/"* || "$file" == "skills/"* || "$file" == "design-systems/"* || "$file" == "design-templates/"* || "$file" == "craft/"* || "$file" == "prompt-templates/"* || "$file" == "scripts/update-nix-pnpm-deps-hash.ts" ]]; then
+              if [[ "$file" == "package.json" || "$file" == "pnpm-lock.yaml" || "$file" == "pnpm-workspace.yaml" || "$file" == "flake.nix" || "$file" == "flake.lock" || "$file" == "nix/"* || "$file" == ".github/workflows/ci.yml" || "$file" == ".github/workflows/nix-check.yml" || "$file" == ".github/workflows/nix-hash-autofix.yml" || "$file" == "apps/daemon/"* || "$file" == "apps/web/"* || "$file" == "packages/components/"* || "$file" == "packages/contracts/"* || "$file" == "packages/registry-protocol/"* || "$file" == "packages/agui-adapter/"* || "$file" == "packages/plugin-runtime/"* || "$file" == "packages/sidecar-proto/"* || "$file" == "packages/sidecar/"* || "$file" == "packages/platform/"* || "$file" == "packages/diagnostics/"* || "$file" == "packages/host/"* || "$file" == "assets/"* || "$file" == "plugins/"* || "$file" == "skills/"* || "$file" == "design-systems/"* || "$file" == "design-templates/"* || "$file" == "craft/"* || "$file" == "prompt-templates/"* || "$file" == "scripts/update-nix-pnpm-deps-hash.ts" ]]; then
                 nix_validation_required=true
               fi
               case "$file" in

From 0b28c3a89c2e0e736be2ff066034599f0379040c Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Fri, 29 May 2026 17:16:46 +0800
Subject: [PATCH 18/22] fix(pack): include components in linux internal
 packages

Generated-By: looper 0.9.2 (runner=fixer, agent=opencode)
---
 tools/pack/src/linux.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tools/pack/src/linux.ts b/tools/pack/src/linux.ts
index adb677626..95afdad1a 100644
--- a/tools/pack/src/linux.ts
+++ b/tools/pack/src/linux.ts
@@ -47,6 +47,7 @@ const CONTAINER_NODE_VERSION = "24.14.1";
 const CONTAINER_TOOLS_PACK_CLI_PATH = "tools/pack/bin/tools-pack.mjs";
 
 export const INTERNAL_PACKAGES = [
+  { directory: "packages/components", name: "@open-design/components" },
   { directory: "packages/contracts", name: "@open-design/contracts" },
   { directory: "packages/registry-protocol", name: "@open-design/registry-protocol" },
   { directory: "packages/sidecar-proto", name: "@open-design/sidecar-proto" },

From 6f87f32d90a94dd561bcadf4c401a4a6850da4b5 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Fri, 29 May 2026 17:31:12 +0800
Subject: [PATCH 19/22] fix(pack): ship components package in packed installs

Generated-By: looper 0.9.2 (runner=fixer, agent=opencode)
---
 packages/components/package.json | 4 ++--
 tools/pack/src/mac/constants.ts  | 1 +
 tools/pack/src/win/constants.ts  | 1 +
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/components/package.json b/packages/components/package.json
index 4c3cd1cad..422e9d3d2 100644
--- a/packages/components/package.json
+++ b/packages/components/package.json
@@ -12,8 +12,8 @@
   ],
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
     },
     "./styles.css": "./src/styles.css"
   },
diff --git a/tools/pack/src/mac/constants.ts b/tools/pack/src/mac/constants.ts
index 25aaa75de..978d5f7b9 100644
--- a/tools/pack/src/mac/constants.ts
+++ b/tools/pack/src/mac/constants.ts
@@ -1,6 +1,7 @@
 export const PRODUCT_NAME = "Open Design";
 
 export const INTERNAL_PACKAGES = [
+  { directory: "packages/components", name: "@open-design/components" },
   { directory: "packages/contracts", name: "@open-design/contracts" },
   { directory: "packages/registry-protocol", name: "@open-design/registry-protocol" },
   { directory: "packages/sidecar-proto", name: "@open-design/sidecar-proto" },
diff --git a/tools/pack/src/win/constants.ts b/tools/pack/src/win/constants.ts
index 030421e1c..ab1c5c656 100644
--- a/tools/pack/src/win/constants.ts
+++ b/tools/pack/src/win/constants.ts
@@ -30,6 +30,7 @@ export const NSIS_INSTALLER_LANGUAGE_BY_WEB_LOCALE = {
   "zh-TW": "zh_TW",
 } as const;
 export const INTERNAL_PACKAGES = [
+  { directory: "packages/components", name: "@open-design/components" },
   { directory: "packages/contracts", name: "@open-design/contracts" },
   { directory: "packages/registry-protocol", name: "@open-design/registry-protocol" },
   { directory: "packages/sidecar-proto", name: "@open-design/sidecar-proto" },

From b031124e3e874798a0be61bfb1ca61aaa2469dcb Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Fri, 29 May 2026 17:37:51 +0800
Subject: [PATCH 20/22] fix(pack): align win app test with internal packages

Generated-By: looper 0.9.2 (runner=fixer, agent=opencode)
---
 tools/pack/tests/win-app.test.ts | 16 ++--------------
 1 file changed, 2 insertions(+), 14 deletions(-)

diff --git a/tools/pack/tests/win-app.test.ts b/tools/pack/tests/win-app.test.ts
index 398037040..d197c2127 100644
--- a/tools/pack/tests/win-app.test.ts
+++ b/tools/pack/tests/win-app.test.ts
@@ -5,22 +5,10 @@ import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 
 import type { ToolPackConfig } from "../src/config.js";
+import { INTERNAL_PACKAGES } from "../src/win/constants.js";
 import { createWorkspaceTarballsCacheKey } from "../src/win/app.js";
 
-const PACKAGE_DIRS = [
-  "packages/contracts",
-  "packages/registry-protocol",
-  "packages/sidecar-proto",
-  "packages/sidecar",
-  "packages/platform",
-  "packages/agui-adapter",
-  "packages/plugin-runtime",
-  "packages/diagnostics",
-  "apps/daemon",
-  "apps/web",
-  "apps/desktop",
-  "apps/packaged",
-] as const;
+const PACKAGE_DIRS = INTERNAL_PACKAGES.map((packageInfo) => packageInfo.directory);
 
 async function writeWorkspace(root: string): Promise<void> {
   await writeFile(join(root, "package.json"), `${JSON.stringify({ packageManager: "pnpm@10.33.2" }, null, 2)}\n`, "utf8");

From 7653e3e18842a9063ae2fd89e3ca8dbc98969ab3 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Fri, 29 May 2026 17:41:37 +0800
Subject: [PATCH 21/22] fix(components): use global visually hidden class

Generated-By: looper 0.9.2 (runner=fixer, agent=opencode)
---
 packages/components/src/visually-hidden.module.css | 11 -----------
 packages/components/src/visually-hidden.tsx        |  3 +--
 2 files changed, 1 insertion(+), 13 deletions(-)
 delete mode 100644 packages/components/src/visually-hidden.module.css

diff --git a/packages/components/src/visually-hidden.module.css b/packages/components/src/visually-hidden.module.css
deleted file mode 100644
index 54092d69c..000000000
--- a/packages/components/src/visually-hidden.module.css
+++ /dev/null
@@ -1,11 +0,0 @@
-.visuallyHidden {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  padding: 0;
-  margin: -1px;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border: 0;
-}
diff --git a/packages/components/src/visually-hidden.tsx b/packages/components/src/visually-hidden.tsx
index c1a014764..1a9b47fd7 100644
--- a/packages/components/src/visually-hidden.tsx
+++ b/packages/components/src/visually-hidden.tsx
@@ -1,12 +1,11 @@
 import type { HTMLAttributes, ReactNode } from 'react';
 
 import { joinClassNames } from './class-names';
-import styles from './visually-hidden.module.css';
 
 export interface VisuallyHiddenProps extends HTMLAttributes<HTMLSpanElement> {
   children: ReactNode;
 }
 
 export function VisuallyHidden({ children, className, ...props }: VisuallyHiddenProps) {
-  return <span className={joinClassNames(styles.visuallyHidden, className)} {...props}>{children}</span>;
+  return <span className={joinClassNames('sr-only', className)} {...props}>{children}</span>;
 }

From b0c0559198cad1969e3a86cf80da5e8b74721cb7 Mon Sep 17 00:00:00 2001
From: mrcfps <mrc@powerformer.com>
Date: Fri, 29 May 2026 18:13:15 +0800
Subject: [PATCH 22/22] fix(components): add development export for source
 builds

Generated-By: looper 0.9.2 (runner=fixer, agent=opencode)
---
 packages/components/package.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/components/package.json b/packages/components/package.json
index 422e9d3d2..5a14801e5 100644
--- a/packages/components/package.json
+++ b/packages/components/package.json
@@ -13,6 +13,7 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
       "default": "./dist/index.mjs"
     },
     "./styles.css": "./src/styles.css"