@kiefer-tek/sophea-design-system 0.15.0

package/README.md

@@ -0,0 +1,141 @@
+# @kiefer-tek/sophea-design-system
+
+Tokens + React components for all Sophea products (Sophea Nous, Sophea Portal, and beyond).
+
+Source of truth for design comes from Claude Design (handoff bundle at `docs/`). This package is the executable form — published as `@kiefer-tek/sophea-design-system`, consumed by `sophea-nous/web` and `sophea-nous-portal`.
+
+## Layout
+
+```
+design-system/
+├── package.json, tsconfig.json, tsup.config.ts
+├── .storybook/             Storybook 8 (React + Vite)
+├── src/
+│   ├── tokens/             colors_and_type.css, tokens.json, Tailwind preset
+│   ├── components/         Button, Input, Badge, ... (one folder each)
+│   ├── assets/             logos, connector marks
+│   └── index.ts            public surface
+└── docs/
+    ├── design-spec.md      full spec (read first)
+    ├── HANDOFF.md          original Claude Design handoff README
+    ├── SKILL.md, CHANGELOG.md
+    ├── chats/              design conversation transcripts
+    └── reference/
+        ├── preview/        77 HTML prototype cards (visual spec)
+        ├── ui_kits/        chat-surface recreation
+        └── scraps/         iteration screenshots
+```
+
+## Install (from GitHub Packages)
+
+This package is published to **GitHub Packages** (Kiefer-Tek org, Internal visibility). Consumers
+need a scoped registry entry and an auth token with `read:packages`.
+
+Add a `.npmrc` in the consuming project:
+
+```
+@kiefer-tek:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
+```
+
+The committed `.npmrc` carries only the literal `${NODE_AUTH_TOKEN}` placeholder — npm expands it
+from the environment at install time, so no secret is committed. Then:
+
+- **CI (in-repo consumers):** the repo's own `GITHUB_TOKEN` is exported as `NODE_AUTH_TOKEN`; no
+  managed secret needed.
+- **Local dev:** export a GitHub PAT with `read:packages` as `NODE_AUTH_TOKEN` (e.g.
+  `export NODE_AUTH_TOKEN=$(gh auth token)`), otherwise `npm install` against an Internal package
+  returns `401`.
+
+```bash
+npm install @kiefer-tek/sophea-design-system
+```
+
+### Building this package locally
+
+```bash
+cd design-system
+npm install
+npm run tokens:build && npm run build
+```
+
+## Usage
+
+### Tokens (CSS)
+
+```css
+@import "@kiefer-tek/sophea-design-system/tokens.css";
+```
+
+Exposes all CSS variables in light + dark scope: `--theme-primary-05`, `--text-04`, `--surface-s2`, `--elevation-2-shadow`, `--density-row`, etc. Dark mode flips via `[data-theme="dark"]` or `prefers-color-scheme`.
+
+### Tailwind preset
+
+```ts
+// tailwind.config.ts
+import sopheaPreset from "@kiefer-tek/sophea-design-system/tailwind-preset";
+
+export default {
+  presets: [sopheaPreset],
+  content: ["./src/**/*.{ts,tsx}"],
+};
+```
+
+### Components
+
+```tsx
+import { Button, Input, Badge } from "@kiefer-tek/sophea-design-system";
+
+<Button variant="primary">Send</Button>
+<Input label="Workspace" placeholder="Acme" />
+<Badge tone="success" dot>Indexed</Badge>
+```
+
+## Scripts
+
+| Script | Purpose |
+|---|---|
+| `npm run build` | Bundle to `dist/` via tsup (ESM + types) |
+| `npm run dev` | Watch-mode build |
+| `npm run storybook` | Storybook on `:6006` |
+| `npm run build-storybook` | Static Storybook |
+| `npm run typecheck` | tsc --noEmit |
+| `npm run lint` | ESLint |
+| `npm run format` | Prettier write |
+
+## Roadmap
+
+This package is implemented in waves. Each wave is a separate PR.
+
+| Wave | Scope | Status |
+|---|---|---|
+| 0 — Infra | Tokens, build, Storybook, package skeleton | done |
+| 1 — Proof | Button, Input, Badge | done |
+| 2 — Controls | Checkbox, Radio, Switch, Select, Datepicker | done |
+| 3 — Surface / feedback | Modal, Toast, Tooltip, Banner, Skeleton, Drawer | done |
+| 4 — Layout / nav | Sidebar tab, Breadcrumbs, Tabs, Pagination | done |
+| 5 — Data display | Table, Avatar, Code, Attachment | done |
+| 6 — AI-specific | Message, AI anatomy, Citation, Empty | done |
+| 7 — Patterns | EmptyHierarchy, ErrorRecovery, Filtering, Forms, LoadingStates (Login skipped) | done |
+| 8 — Adoption | Gradual migration in `sophea-nous/web` + Portal | pending |
+
+Component reference (77 cards) lives at `docs/reference/preview/`. Open the corresponding `*.html` to see the target visual for each component before implementing.
+
+## Design contract (read first)
+
+Full contract at `docs/design-spec.md`. Highlights every contributor must respect:
+
+- **Tokens, not raw hex.** Use `var(--text-04)`, not `#475569`.
+- **Lucide icons only**, stroke 1.5 (Send arrow 2.75).
+- **One primary CTA in view.** Brand gradient is the signature.
+- **Glass is for chrome only.** Never for body content. Never glass-on-glass.
+- **Drift motion language.** 6 named patterns; never invent new ones.
+- **WCAG 2.2 floors.** Focus ring ≥ 2 px + 2 px offset, target size ≥ 24 px, honour `prefers-reduced-*`.
+- **No emoji.** Anywhere.
+- **Greek-first.** Greek runs ~15% longer; design hit targets for it.
+
+## Sources
+
+- Original design handoff: Claude Design bundle (see `docs/HANDOFF.md` + `docs/chats/`)
+- Codebase parity: `sophea-nous/web/src/app/css/sophea_v1.css`, `web/lib/opal/src/`, `web/AGENTS.md`
+- Workspace conventions: `../AGENTS.md` (root)

package/dist/ai-surface/RenderAgentComponent.d.ts

@@ -0,0 +1,67 @@
+import { ReactNode } from 'react';
+export type AgentFormField = {
+    kind: "text";
+    name: string;
+    label: string;
+    placeholder?: string;
+    defaultValue?: string;
+    required?: boolean;
+    hint?: string;
+} | {
+    kind: "select";
+    name: string;
+    label: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    defaultValue?: string;
+} | {
+    kind: "switch";
+    name: string;
+    label: string;
+    description?: string;
+    defaultValue?: boolean;
+};
+export type AgentChartPoint = {
+    label: string;
+    value: number;
+};
+export type AgentComponentSpec = {
+    kind: "form";
+    title?: string;
+    fields: AgentFormField[];
+    submitLabel?: string;
+    cancelLabel?: string;
+} | {
+    kind: "chart";
+    title?: string;
+    variant: "bar" | "sparkline";
+    data: AgentChartPoint[];
+    unit?: string;
+    caption?: string;
+} | {
+    kind: "confirm";
+    title: string;
+    body: string;
+    approveLabel?: string;
+    rejectLabel?: string;
+    danger?: boolean;
+};
+export interface RenderAgentComponentProps {
+    spec: AgentComponentSpec;
+    /** Fires when a form submit is triggered. */
+    onSubmit?: (values: Record<string, string | boolean>) => void;
+    /** Fires when the secondary CTA fires (form cancel / confirm reject). */
+    onCancel?: () => void;
+    /** Fires when a confirm dialog is approved. */
+    onApprove?: () => void;
+    /** Fires when a confirm dialog is rejected. Aliased to onCancel by default. */
+    onReject?: () => void;
+}
+export declare const RenderAgentComponent: import('react').ForwardRefExoticComponent<RenderAgentComponentProps & import('react').RefAttributes<HTMLDivElement>>;
+export declare function AgentSpecPreview({ spec, caption, }: {
+    spec: AgentComponentSpec;
+    caption?: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=RenderAgentComponent.d.ts.map

package/dist/ai-surface/RenderAgentComponent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderAgentComponent.d.ts","sourceRoot":"","sources":["../../src/ai-surface/RenderAgentComponent.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAmB7D,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEN,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D,MAAM,MAAM,kBAAkB,GAC1B;IACE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,KAAK,GAAG,WAAW,CAAC;IAC7B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEN,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,kBAAkB,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC;IAC9D,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAMD,eAAO,MAAM,oBAAoB,sHAwBhC,CAAC;AA2PF,wBAAgB,gBAAgB,CAAC,EAC/B,IAAI,EACJ,OAAO,GACR,EAAE;IACD,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB,2CAUA"}

package/dist/ai-surface/index.d.ts

@@ -0,0 +1,2 @@
+export * from './RenderAgentComponent';
+//# sourceMappingURL=index.d.ts.map

package/dist/ai-surface/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai-surface/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}