@dybo-ai/design 1.0.1

package/CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+`@dybo-ai/design` — the DYBO design system packaged as an installable npm module (private, published to GitHub Packages). It ships design tokens, a Tailwind preset, plain CSS + helper classes, and a handful of React components. There is no build step, bundler, test suite, or linter configured — every file in the package is hand-authored and published as-is (see `files` in `package.json`).
+
+This `CLAUDE.md` is itself shipped to consumers (it's in `package.json`'s `files` list) and is meant to be copied into a consuming app's own `CLAUDE.md` — see "Design system rules for consuming apps" below. Keep that section self-contained and consumer-facing; put repo-maintenance notes in the sections after it instead of mixing them in.
+
+## Architecture: one source of truth, four hand-synced mirrors
+
+`tokens.json` is canonical (values + original Figma variable names). Every other token surface is a **manually maintained mirror** of it — there is no code generation:
+
+| File | Mirrors tokens.json as... |
+|---|---|
+| `tokens.mjs` | ESM flat exports (`color`, `space`, `radius`, etc.) |
+| `tokens.cjs` | CommonJS mirror of `tokens.mjs` |
+| `theme.css` | CSS custom properties + `.dybo-*` helper classes (`.dybo-glass`, `.dybo-btn`, `.dybo-input`, `.dybo-badge`) |
+| `tailwind-preset.cjs` | Tailwind theme extension (`dybo-*` utilities) |
+| `react/index.jsx` | Thin React wrappers (`Button`, `Card`, `Input`, `Badge`) over the `theme.css` classes — requires the consumer to import `theme.css` separately |
+
+**When changing a token value or adding a new one, update all five in the same change.** There's no automated check that catches drift between them (a Style Dictionary generation pipeline is proposed but not implemented — see `docs/SETUP.md` Part E).
+
+`assets/` holds static brand image files (currently the logo) — it's shipped via `package.json`'s `files` list and importable as `@dybo-ai/design/assets/<file>`, but it's not part of the token-mirror sync described above.
+
+`docs/design-system.md` is the narrative reference extracted from Figma (file `ZHtkvTEeTYlNVbSncLyI1a`) — it's the rationale/source document behind `tokens.json`, including a documented naming quirk (Figma's "Feedback Colors/Error" is actually orange; the real red danger color is `Brand/Danger/700` / `#a21a17`).
+
+## Commands
+
+There is no build, lint, or test tooling in this repo — don't invent npm scripts that don't exist (`package.json` has no `scripts` field).
+
+Publishing (manual, no CI):
+```bash
+npm version patch   # or minor / major — see docs/SETUP.md Part D for the semver rule
+npm publish
+git push --follow-tags
+```
+`npm publish --dry-run` is useful to confirm the packed file list matches `package.json`'s `files` array before actually publishing. Publishing requires a `.npmrc` (git-ignored, copy from `.npmrc.example`) with a `GITHUB_TOKEN` that has `write:packages`.
+
+## Design system rules for consuming apps
+
+When building UI in a DYBO app, use `@dybo-ai/design`. Do not hard-code hex values or ad-hoc spacing — reference tokens.
+
+- **Font:** Urbanist (400/500/600/700). Titles use weight 400 with 1px letter-spacing; body uses weight 500.
+- **Style:** glassmorphism — translucent cards `rgba(240,241,244,0.70)`, 1px white stroke, 20px radius, soft blue-gray shadow, 4px backdrop blur, on a `#e6eaf0` page.
+- **Key colors:** primary/ink `#0a1323`, blue accent `#5878a7`, logo navy `#1d335c`. Semantic: success `#20a156`, warning `#f16c24`, danger `#a21a17`.
+- **Spacing:** 4px scale — 4/8/12/16/20/32.
+- **Radius:** 12 (buttons/inputs), 20 (cards), 999 (pills).
+
+How to consume (pick per app):
+- Tailwind app → `presets: [require("@dybo-ai/design/tailwind")]`, use `dybo-*` utilities.
+- Non-Tailwind → `import "@dybo-ai/design/theme.css"` and use `.dybo-glass`, `.dybo-btn`, `.dybo-input`, `.dybo-badge`.
+- React → `import { Button, Card, Input, Badge } from "@dybo-ai/design/react"` (also import the CSS).
+- Programmatic values → `import { color, space, radius } from "@dybo-ai/design"`.
+
+Reference `tokens.json` for the full token list and `docs/design-system.md` for rationale. Semantic "danger" is red `#a21a17` — ignore Figma's mislabeled orange "Feedback/Error".

package/README.md

@@ -0,0 +1,346 @@
+# @dybo-ai/design
+
+DYBO design system — tokens, CSS theme, Tailwind V4 support, and React components with TypeScript.  
+Style: **glassmorphism** · Font: **Urbanist** · Published on [npmjs.com](https://www.npmjs.com).
+
+---
+
+## Installation
+
+```bash
+npm install @dybo-ai/design
+```
+
+Load the Urbanist font once in your HTML (or via `@fontsource/urbanist`):
+
+```html
+<link
+  href="https://fonts.googleapis.com/css2?family=Urbanist:wght@400;500;600;700&display=swap"
+  rel="stylesheet"
+/>
+```
+
+---
+
+## Tailwind V4
+
+Add one line to your app's main CSS file:
+
+```css
+/* app.css */
+@import "tailwindcss";
+@import "@dybo-ai/design/theme.css";
+```
+
+This automatically registers all DYBO utilities via `@theme`:
+
+| Utility          | Example                                                                 |
+| ---------------- | ----------------------------------------------------------------------- |
+| `bg-dybo-*`      | `bg-dybo-blue`, `bg-dybo-page`, `bg-dybo-danger`                        |
+| `text-dybo-*`    | `text-dybo-ink`, `text-dybo-muted`, `text-dybo-on-dark`                 |
+| `border-dybo-*`  | `border-dybo-line`                                                      |
+| `rounded-dybo-*` | `rounded-dybo-sm` (12px), `rounded-dybo-md` (20px), `rounded-dybo-full` |
+| `shadow-dybo-*`  | `shadow-dybo-card`, `shadow-dybo-drop`                                  |
+| `blur-dybo`      | 4px backdrop blur                                                       |
+
+**No Tailwind?** Import only the CSS — all variables and `.dybo-*` classes work in any framework:
+
+```js
+import "@dybo-ai/design/theme.css";
+```
+
+---
+
+## React Components
+
+```tsx
+import "@dybo-ai/design/theme.css";
+import { Button, Card, Input, Badge } from "@dybo-ai/design/react";
+```
+
+All components are TypeScript with `I`-prefixed interfaces.
+
+### Available components
+
+| Category       | Components                                           |
+| -------------- | ---------------------------------------------------- |
+| **Base**       | `Button`, `Card`, `Input`, `Badge`                   |
+| **Layout**     | `AppShell`, `Sidebar`, `TopBar`                      |
+| **Navigation** | `NavItem`, `NavSection`                              |
+| **Data**       | `DataTable`, `Tabs`, `OverviewGrid`, `OverviewField` |
+| **Form**       | `Select`                                             |
+| **Feedback**   | `Alert`                                              |
+| **Overlay**    | `Modal`                                              |
+| **Auth**       | `LoginCard`                                          |
+
+---
+
+## Examples
+
+### Full app shell
+
+```tsx
+import "@dybo-ai/design/theme.css";
+import {
+  AppShell,
+  Sidebar,
+  TopBar,
+  NavItem,
+  NavSection,
+} from "@dybo-ai/design/react";
+
+function MyApp() {
+  return (
+    <AppShell
+      sidebar={
+        <Sidebar
+          brand={<img src="/logo.png" alt="DYBO" height={36} />}
+          user={{ name: "Jane Smith", email: "jane@dybo.ai" }}
+          onLogout={() => logout()}
+        >
+          <NavSection label="Dashboard" />
+          <NavItem label="Overview" href="/" active />
+          <NavItem label="Projects" href="/projects" />
+          <NavSection label="Settings" />
+          <NavItem label="Parameters" href="/settings" />
+        </Sidebar>
+      }
+      topBar={<TopBar title="Tax Calculator 2026" />}
+    >
+      {/* page content */}
+    </AppShell>
+  );
+}
+```
+
+### Glassmorphism card
+
+```tsx
+import { Card, Button, Input } from "@dybo-ai/design/react";
+
+<Card>
+  <Input label="Name" placeholder="Enter your name" />
+  <Button variant="primary" style={{ marginTop: 16 }}>
+    Save
+  </Button>
+</Card>;
+```
+
+### DataTable
+
+```tsx
+import { DataTable } from "@dybo-ai/design/react";
+import type { IColumn } from "@dybo-ai/design/react";
+
+interface IUser {
+  id: number;
+  name: string;
+  email: string;
+  status: string;
+}
+
+const columns: IColumn<IUser>[] = [
+  { key: "name", label: "Name", align: "left" },
+  { key: "email", label: "Email", align: "left" },
+  {
+    key: "status",
+    label: "Status",
+    format: (v) => <Badge status="success">{String(v)}</Badge>,
+  },
+];
+
+<DataTable
+  columns={columns}
+  rows={users}
+  rowKey="id"
+  onRowClick={(user) => navigate(`/users/${user.id}`)}
+/>;
+```
+
+### Tabs
+
+```tsx
+import { useState } from "react";
+import { Tabs } from "@dybo-ai/design/react";
+
+const TABS = [
+  { key: "federal", label: "Federal (IRS)" },
+  { key: "state", label: "State" },
+  { key: "annual", label: "Annual Inputs" },
+];
+
+function ProjectDetail() {
+  const [tab, setTab] = useState("federal");
+  return (
+    <>
+      <Tabs tabs={TABS} active={tab} onChange={setTab} />
+      {tab === "federal" && <FederalView />}
+      {tab === "state" && <StateView />}
+      {tab === "annual" && <AnnualInputs />}
+    </>
+  );
+}
+```
+
+### Overview grid
+
+```tsx
+import { OverviewGrid } from "@dybo-ai/design/react";
+
+<OverviewGrid
+  fields={[
+    { label: "Entity", value: "Jestor Holdings Inc" },
+    { label: "State", value: "DE" },
+    { label: "Federal Tax", value: "$1,432.00" },
+    { label: "State Tax", value: "$312.00" },
+  ]}
+/>;
+```
+
+### Alert
+
+```tsx
+import { Alert } from "@dybo-ai/design/react";
+
+<Alert variant="danger" onClose={() => setError(null)}>
+  Failed to save. Please check the data and try again.
+</Alert>;
+```
+
+### Modal
+
+```tsx
+import { useState } from "react";
+import { Modal, Button } from "@dybo-ai/design/react";
+
+function ConfirmDelete() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="danger" onClick={() => setOpen(true)}>
+        Delete
+      </Button>
+      <Modal
+        open={open}
+        onClose={() => setOpen(false)}
+        title="Confirm deletion"
+        footer={
+          <>
+            <Button variant="ghost" onClick={() => setOpen(false)}>
+              Cancel
+            </Button>
+            <Button variant="danger" onClick={handleDelete}>
+              Delete
+            </Button>
+          </>
+        }
+      >
+        <p>This action cannot be undone. Do you want to continue?</p>
+      </Modal>
+    </>
+  );
+}
+```
+
+### Login card
+
+```tsx
+import { LoginCard, Input, Button } from "@dybo-ai/design/react";
+
+<LoginCard
+  logo={<img src="/logo.png" alt="DYBO" height={44} />}
+  subtitle="Sign in to your account"
+>
+  <form onSubmit={handleSubmit}>
+    <Input label="Email" type="email" name="email" />
+    <Input
+      label="Password"
+      type="password"
+      name="password"
+      style={{ marginTop: 14 }}
+    />
+    <Button
+      variant="primary"
+      type="submit"
+      style={{ width: "100%", marginTop: 20 }}
+    >
+      Sign in
+    </Button>
+  </form>
+</LoginCard>;
+```
+
+### Select
+
+```tsx
+import { Select } from "@dybo-ai/design/react";
+
+<Select
+  label="State"
+  placeholder="Select…"
+  options={[
+    { value: "CA", label: "California" },
+    { value: "DE", label: "Delaware" },
+    { value: "NY", label: "New York" },
+  ]}
+  onChange={(e) => setState(e.target.value)}
+/>;
+```
+
+---
+
+## Tokens in JS/TS
+
+```ts
+import { color, space, radius } from "@dybo-ai/design";
+
+color.brand.blue; // "#5878a7"
+color.semantic.danger.solid; // "#a21a17"
+space["200"].value; // 16
+radius.medium.value; // 20
+```
+
+---
+
+## Assets
+
+```ts
+import logo from "@dybo-ai/design/assets/logo-dybo-01.jpeg"; // opaque JPEG
+import logoLight from "@dybo-ai/design/assets/logo-dybo-01.png"; // PNG transparent background, navy ink (light surfaces)
+import logoDark from "@dybo-ai/design/assets/logo-dybo-01-dark.png"; // PNG transparent background, light ink (dark surfaces)
+```
+
+---
+
+## Customization via CSS variables
+
+All tokens are CSS custom properties. To override selectively:
+
+```css
+/* Override in a specific component */
+.my-sidebar {
+  --dybo-sidebar-bg: #0a1323;
+  --dybo-sidebar-width: 260px;
+}
+
+/* Global override */
+:root {
+  --dybo-color-brand-blue-yonder: #4a6fa0; /* your blue shade */
+}
+```
+
+---
+
+## Publishing guide
+
+For maintainers (how to publish a new version): see [`docs/PUBLISHING.md`](./docs/PUBLISHING.md).
+
+---
+
+## Token reference
+
+`tokens.json` contains all values with the original Figma names.  
+`docs/design-system.md` contains the design rationale extracted from Figma.
+
+> **Semantic note**: The system's "danger" is red `#a21a17` (`Brand/Danger/700`).  
+> Figma has a color called "Feedback Colors/Error" that is orange — that's `warning`, not `danger`.