@bevlogic/style-system 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `@bevlogic/style-system` are recorded here. This package
+follows [semver](https://semver.org/): consuming apps pin a version and upgrade
+on their own schedule — a new major means "there's breaking work to do, do it
+when you have cycles," not "everything is broken now."
+
+## [0.1.0]
+
+Initial release.
+
+### Added
+- `tokens.css`: canonical design tokens (color palette, surfaces, text, brand,
+  an 8px spacing scale, a named type scale, radii, shadows) plus a restrained set
+  of gradient tokens (`--grad-*`) for sidebars, accents, surfaces, and panels.
+- `brand-mark.svg` and the `--brand-mark` token (the mark as a CSS `mask` value),
+  so the brand mark can be painted in any token color from one source.
+- `icons.svg`: an 80-symbol icon sprite (Lucide-derived), with a general-purpose
+  `ui` tier alongside the domain icons.
+- `icons.json`: the icon catalog (label, category, "use for") so icons are picked
+  by intent.
+- `recipes/`: core components (button, card, badge, input, table, app shell)
+  shown for React, static HTML, and PHP, all driven by the same tokens.

package/README.md

@@ -0,0 +1,65 @@
+# @bevlogic/style-system
+
+The single source of truth for BevLogic UI: design tokens, the icon sprite, and
+the brand mark. Consume these so interfaces stay visually consistent, and upgrade
+on your own schedule via the package version.
+
+## What's in here
+
+| File | What it is |
+| --- | --- |
+| `tokens.css` | Canonical CSS custom properties (color, spacing, type, radii, shadows, gradients). **The load-bearing file.** |
+| `icons.svg` | Icon sprite (80 symbols), Lucide-derived. |
+| `icons.json` | Icon catalog: label, category, and "use for" per icon. Pick by intent. |
+| `brand-mark.svg` | The BevLogic brand mark (also available as the `--brand-mark` CSS token). |
+| `recipes/` | Core components shown three ways: React, static HTML, and PHP. Same look, one token set. |
+
+## Install
+
+```
+yarn add @bevlogic/style-system
+```
+
+```css
+@import "@bevlogic/style-system/tokens.css";
+```
+
+Subpath exports (`/tokens.css`, `/icons.svg`, `/icons.json`, `/brand-mark.svg`)
+are declared in `package.json`. There is no `.` export, so always import a
+subpath, not the bare package name.
+
+Reference tokens by name:
+
+```css
+.button { background: var(--accent); color: var(--text-on-accent); }
+```
+
+Icons via the sprite:
+
+```html
+<svg><use href="/path/to/icons.svg#i-search" /></svg>
+```
+
+The brand mark can be painted with any color via the token:
+
+```css
+.brand-dot {
+  width: 20px; height: 20px;
+  background: var(--accent);
+  mask: var(--brand-mark) center / contain no-repeat;
+}
+```
+
+## Ground rules
+
+1. **Consume tokens, don't fork values.** Need a value that isn't here? Add a
+   token upstream, don't hardcode a hex/px.
+2. **8px spacing grid.** Prefer multiples of 8; `--space-half` (4px) is an escape
+   hatch, not a normal step.
+3. **One icon system.** Use the sprite; don't hand-copy SVG paths.
+
+## Versioning
+
+Follows [semver](https://semver.org/): pin a version and upgrade when you have
+cycles. A new major means there is breaking work to do, not that everything is
+broken now.

package/brand-mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" fill="#000"><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(0 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(18 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(36 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(54 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(72 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(90 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(108 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(126 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(144 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(162 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(180 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(198 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(216 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(234 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(252 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(270 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(288 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(306 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(324 50 50)"/><ellipse cx="50" cy="17" rx="3.2" ry="7" transform="rotate(342 50 50)"/></svg>

package/icons.json

@@ -0,0 +1,93 @@
+{
+  "$comment": "Canonical BevLogic icon catalog. Every id maps to a <symbol id=\"i-<id>\"> in icons.svg. Use this to pick the right icon by intent. Most icons are Lucide (ISC); 'lucide: null' means a custom glyph with no Lucide equivalent.",
+  "spriteUrl": "icons.svg",
+  "categories": {
+    "admin": "Internal admin shell — the staff-facing product.",
+    "client": "Customer portal — the client-facing surface.",
+    "util": "Utility / cross-cutting (navigation, fallback, auth state).",
+    "ui": "General-purpose interface glyphs — search, actions, disclosure, status. Stack-agnostic.",
+    "rcrv1": "Returns filing surface (RCRv1)."
+  },
+  "icons": [
+    { "id": "dashboard",            "label": "Dashboard",            "category": "admin",  "lucide": "layout-grid",        "use": "Main admin dashboard / index landing page." },
+    { "id": "inbox",                "label": "Inbox",                "category": "admin",  "lucide": "inbox",              "use": "Inbox of incoming tasks, messages, or items needing action." },
+    { "id": "calendar",             "label": "Calendar",             "category": "admin",  "lucide": "calendar-days",      "use": "Filing calendar and upcoming deadlines." },
+    { "id": "notifications",        "label": "Notifications",        "category": "admin",  "lucide": "bell",               "use": "Bell — system notifications, alerts, mentions." },
+    { "id": "accounts",             "label": "Accounts",             "category": "admin",  "lucide": "user",               "use": "Account directory / customer list." },
+    { "id": "returns",              "label": "Returns",              "category": "admin",  "lucide": "repeat-2",           "use": "Tax return filings — the Returns service module." },
+    { "id": "registrations",        "label": "Registrations",        "category": "admin",  "lucide": "file-text",          "use": "State registration filings and status." },
+    { "id": "licenses",             "label": "Licenses",             "category": "admin",  "lucide": "id-card",            "use": "License and permit tracking." },
+    { "id": "filings",              "label": "Filings",              "category": "admin",  "lucide": "folder",             "use": "Generic filings module — uploads, drafts, submitted." },
+    { "id": "reports",              "label": "Reports",              "category": "admin",  "lucide": "chart-column-big",   "use": "Reports, exports, analytics output." },
+    { "id": "settings",             "label": "Settings",             "category": "admin",  "lucide": "settings",           "use": "Workspace, tenant, and personal configuration." },
+    { "id": "ingestion",            "label": "Ingestion",            "category": "admin",  "lucide": "cloud-upload",       "use": "Data ingest pipelines — file uploads, agency feeds." },
+    { "id": "rates",                "label": "Rates Explorer",       "category": "admin",  "lucide": "circle-dollar-sign", "use": "Tax rates database explorer." },
+    { "id": "notices",              "label": "Notices",              "category": "admin",  "lucide": "mail",               "use": "Notice triage — agency letters, response queue." },
+    { "id": "filing-preview",       "label": "Filing Preview",       "category": "admin",  "lucide": "file-search",        "use": "Preview a generated filing PDF before submission." },
+    { "id": "integration-health",  "label": "Integration Health",   "category": "admin",  "lucide": "activity",           "use": "Connector / external integration status." },
+    { "id": "finance",              "label": "Finance",              "category": "admin",  "lucide": "banknote",           "use": "Finance dashboard — AR, AP, accounting." },
+    { "id": "reconciliation",       "label": "Reconciliation",       "category": "admin",  "lucide": "scale",              "use": "Reconcile finance ledger against filings." },
+    { "id": "quickbooks",           "label": "QuickBooks",           "category": "admin",  "lucide": null,                 "use": "QuickBooks integration page. Custom — no Lucide equivalent." },
+    { "id": "discrepancies",        "label": "Discrepancies",        "category": "admin",  "lucide": "alert-triangle",     "use": "Discrepancy queue — mismatches needing review." },
+    { "id": "period-close",         "label": "Period Close",         "category": "admin",  "lucide": "calendar-check",     "use": "Monthly / period close checklist." },
+    { "id": "client-dashboard",     "label": "Client Dashboard",     "category": "client", "lucide": "gauge",              "use": "Customer portal landing." },
+    { "id": "client-status",        "label": "Client Filing Status", "category": "client", "lucide": "workflow",           "use": "Customer view of their filing status." },
+    { "id": "client-registrations", "label": "Client Registrations", "category": "client", "lucide": "file-text",          "use": "Customer view of their state registrations." },
+    { "id": "client-licenses",      "label": "Client Licenses",      "category": "client", "lucide": "id-card",            "use": "Customer view of their licenses and permits." },
+    { "id": "client-notices",       "label": "Client Notices",       "category": "client", "lucide": "mail",               "use": "Customer-facing notices inbox." },
+    { "id": "client-renewals",      "label": "Client Renewals",      "category": "client", "lucide": "rotate-cw",          "use": "Upcoming renewal actions for the customer." },
+    { "id": "client-products",      "label": "Client Products",      "category": "client", "lucide": "package",            "use": "Customer product catalog / SKUs." },
+    { "id": "client-distributors",  "label": "Client Distributors",  "category": "client", "lucide": "truck",              "use": "Distributor relationships." },
+    { "id": "client-billing",       "label": "Client Billing",       "category": "client", "lucide": "receipt-text",       "use": "Customer invoices, billing history." },
+    { "id": "client-documents",     "label": "Client Documents",     "category": "client", "lucide": "file-text",          "use": "Customer document vault — uploads, signed forms." },
+    { "id": "client-help",          "label": "Client Help",          "category": "client", "lucide": "help-circle",        "use": "Customer help / support center." },
+    { "id": "back-to-admin",        "label": "Back to Admin",        "category": "util",   "lucide": "arrow-left",         "use": "Switch from impersonating client back to admin shell." },
+    { "id": "default",              "label": "Default",              "category": "util",   "lucide": "dot",                "use": "Fallback symbol when a key is missing from the sprite." },
+    { "id": "lock-keyhole",         "label": "Lock",                 "category": "util",   "lucide": "lock-keyhole",       "use": "Locked / authenticated state — secure access, restricted resource." },
+    { "id": "liability-summary",    "label": "Liability Summary",    "category": "rcrv1",  "lucide": "calculator",         "use": "RCRv1 — tax liability summary view." },
+    { "id": "filing-tasks",         "label": "Filing Tasks",         "category": "rcrv1",  "lucide": "list-checks",        "use": "RCRv1 — return filing task list." },
+    { "id": "transactions",         "label": "Transactions",         "category": "rcrv1",  "lucide": "arrow-left-right",   "use": "RCRv1 — transaction browser." },
+    { "id": "import-history",       "label": "Import History",       "category": "rcrv1",  "lucide": "history",            "use": "RCRv1 — file import log." },
+    { "id": "visual-form-editor",   "label": "Form Editor",          "category": "rcrv1",  "lucide": "pencil-ruler",       "use": "RCRv1 — visual form layout editor." },
+    { "id": "chevron-down",       "label": "Chevron Down",       "category": "ui",     "lucide": "chevron-down",     "use": "Disclosure caret — dropdown, accordion, select. Replaces CSS-triangle carets." },
+    { "id": "chevron-up",         "label": "Chevron Up",         "category": "ui",     "lucide": "chevron-up",       "use": "Collapse an expanded disclosure; scroll-to-top affordance." },
+    { "id": "chevron-left",       "label": "Chevron Left",       "category": "ui",     "lucide": "chevron-left",     "use": "Previous page / step in pagination and carousels." },
+    { "id": "chevron-right",      "label": "Chevron Right",      "category": "ui",     "lucide": "chevron-right",    "use": "Next page / step; drill-in affordance on list rows." },
+    { "id": "arrow-left",         "label": "Arrow Left",         "category": "ui",     "lucide": "arrow-left",       "use": "Back navigation. (Domain twin: `back-to-admin`.)" },
+    { "id": "arrow-right",        "label": "Arrow Right",        "category": "ui",     "lucide": "arrow-right",      "use": "Forward navigation; 'continue' on a wizard step." },
+    { "id": "sort",               "label": "Sort",               "category": "ui",     "lucide": "arrow-up-down",    "use": "Sortable table column header (unsorted state)." },
+    { "id": "search",             "label": "Search",             "category": "ui",     "lucide": "search",           "use": "Search input adornment, filter-by-text affordance." },
+    { "id": "plus",               "label": "Add",                "category": "ui",     "lucide": "plus",             "use": "Add / create — 'Add rate', 'New jurisdiction' buttons." },
+    { "id": "x",                  "label": "Close",              "category": "ui",     "lucide": "x",                "use": "Close a drawer, modal, toast, or dismiss a chip." },
+    { "id": "check",              "label": "Check",              "category": "ui",     "lucide": "check",            "use": "Confirm / done / selected item in a menu or list." },
+    { "id": "copy",               "label": "Copy",               "category": "ui",     "lucide": "copy",             "use": "Copy a value to the clipboard — ids, JSON payloads." },
+    { "id": "pencil",             "label": "Edit",               "category": "ui",     "lucide": "pencil",           "use": "Edit an existing record inline or in a drawer." },
+    { "id": "trash",              "label": "Delete",             "category": "ui",     "lucide": "trash-2",          "use": "Delete / remove a record. Pair with `--danger`." },
+    { "id": "download",           "label": "Download",           "category": "ui",     "lucide": "download",         "use": "Export or download a file — CSV, PDF, report." },
+    { "id": "upload",             "label": "Upload",             "category": "ui",     "lucide": "upload",           "use": "Upload a file — imports, document attachments." },
+    { "id": "external-link",      "label": "External Link",      "category": "ui",     "lucide": "external-link",    "use": "Link that opens off-app or in a new tab." },
+    { "id": "filter",             "label": "Filter",             "category": "ui",     "lucide": "filter",           "use": "Open filter controls for a table or list." },
+    { "id": "more",               "label": "More",               "category": "ui",     "lucide": "ellipsis",         "use": "Overflow / kebab menu of secondary row actions." },
+    { "id": "refresh",            "label": "Refresh",            "category": "ui",     "lucide": "rotate-cw",        "use": "Re-fetch or recalculate the current view." },
+    { "id": "log-out",            "label": "Log Out",            "category": "ui",     "lucide": "log-out",          "use": "Sign out — user menu logout item." },
+    { "id": "eye",                "label": "Show",               "category": "ui",     "lucide": "eye",              "use": "Reveal a hidden value; toggle row visibility." },
+    { "id": "eye-off",            "label": "Hide",               "category": "ui",     "lucide": "eye-off",          "use": "Hide a revealed value; the off state of `eye`." },
+    { "id": "info",               "label": "Info",               "category": "ui",     "lucide": "info",             "use": "Informational note or tooltip trigger. Pair with `--info`." },
+    { "id": "alert-triangle",     "label": "Warning",            "category": "ui",     "lucide": "triangle-alert",   "use": "Warning callout / validation caution. Pair with `--warning`." },
+    { "id": "check-circle",       "label": "Success",            "category": "ui",     "lucide": "circle-check",     "use": "Success confirmation in a toast or banner. Pair with `--success`." },
+    { "id": "x-circle",           "label": "Error",              "category": "ui",     "lucide": "circle-x",         "use": "Error state in a toast or banner. Pair with `--danger`." },
+    { "id": "clock",              "label": "Pending",            "category": "ui",     "lucide": "clock",            "use": "Pending / scheduled / awaiting-action state." },
+    { "id": "spinner",            "label": "Loading",            "category": "ui",     "lucide": "loader-circle",    "use": "In-flight state; animate with a CSS spin." },
+    { "id": "package",            "label": "Package",            "category": "ui",     "lucide": "package",          "use": "Generic product / SKU / shipment. (Domain twin: `client-products`.)" },
+    { "id": "truck",              "label": "Truck",              "category": "ui",     "lucide": "truck",            "use": "Generic distribution / shipping. (Domain twin: `client-distributors`.)" },
+    { "id": "history",            "label": "History",            "category": "ui",     "lucide": "history",          "use": "Generic audit trail / change log. (Domain twin: `import-history`.)" },
+    { "id": "folder",             "label": "Folder",             "category": "ui",     "lucide": "folder",           "use": "Generic document or file grouping. (Domain twin: `filings`.)" },
+    { "id": "chart-bar",          "label": "Bar Chart",          "category": "ui",     "lucide": "chart-column-big", "use": "Generic analytics / reporting tile. (Domain twin: `reports`.)" },
+    { "id": "shield",             "label": "Compliance",         "category": "ui",     "lucide": "shield",           "use": "Compliance / protection / permissions section." },
+    { "id": "route",              "label": "Route",              "category": "ui",     "lucide": "route",            "use": "Multi-step flow, distribution path, pipeline." },
+    { "id": "globe",              "label": "Jurisdictions",      "category": "ui",     "lucide": "globe",            "use": "Geography — states, jurisdictions, territories." },
+    { "id": "users",              "label": "Users",              "category": "ui",     "lucide": "users",            "use": "A group of people — teams, contacts, staff list. (Single user: `accounts`.)" },
+    { "id": "sliders",            "label": "Controls",           "category": "ui",     "lucide": "sliders-horizontal","use": "Tunable settings / configuration sliders. (Gear: `settings`.)" },
+    { "id": "plug",               "label": "Integrations",       "category": "ui",     "lucide": "plug",             "use": "External connector / integration setup. (Status: `integration-health`.)" }
+  ]
+}

package/icons.svg

@@ -0,0 +1,83 @@
+<svg xmlns="http://www.w3.org/2000/svg" style="display:none" aria-hidden="true">
+  <symbol id="i-dashboard" viewBox="0 0 24 24"><rect width="7" height="7" x="3" y="3" rx="1" /> <rect width="7" height="7" x="14" y="3" rx="1" /> <rect width="7" height="7" x="14" y="14" rx="1" /> <rect width="7" height="7" x="3" y="14" rx="1" /></symbol>
+  <symbol id="i-inbox" viewBox="0 0 24 24"><polyline points="22 12 16 12 14 15 10 15 8 12 2 12" /> <path d="M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z" /></symbol>
+  <symbol id="i-calendar" viewBox="0 0 24 24"><path d="M8 2v4" /> <path d="M16 2v4" /> <rect width="18" height="18" x="3" y="4" rx="2" /> <path d="M3 10h18" /> <path d="M8 14h.01" /> <path d="M12 14h.01" /> <path d="M16 14h.01" /> <path d="M8 18h.01" /> <path d="M12 18h.01" /> <path d="M16 18h.01" /></symbol>
+  <symbol id="i-notifications" viewBox="0 0 24 24"><path d="M10.268 21a2 2 0 0 0 3.464 0" /> <path d="M3.262 15.326A1 1 0 0 0 4 17h16a1 1 0 0 0 .74-1.673C19.41 13.956 18 12.499 18 8A6 6 0 0 0 6 8c0 4.499-1.411 5.956-2.738 7.326" /></symbol>
+  <symbol id="i-accounts" viewBox="0 0 24 24"><path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" /> <circle cx="12" cy="7" r="4" /></symbol>
+  <symbol id="i-returns" viewBox="0 0 24 24"><path d="m2 9 3-3 3 3" /> <path d="M13 18H7a2 2 0 0 1-2-2V6" /> <path d="m22 15-3 3-3-3" /> <path d="M11 6h6a2 2 0 0 1 2 2v10" /></symbol>
+  <symbol id="i-registrations" viewBox="0 0 24 24"><path d="M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z" /> <path d="M14 2v5a1 1 0 0 0 1 1h5" /> <path d="M10 9H8" /> <path d="M16 13H8" /> <path d="M16 17H8" /></symbol>
+  <symbol id="i-licenses" viewBox="0 0 24 24"><path d="M16 10h2" /> <path d="M16 14h2" /> <path d="M6.17 15a3 3 0 0 1 5.66 0" /> <circle cx="9" cy="11" r="2" /> <rect x="2" y="5" width="20" height="14" rx="2" /></symbol>
+  <symbol id="i-filings" viewBox="0 0 24 24"><path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z" /></symbol>
+  <symbol id="i-reports" viewBox="0 0 24 24"><path d="M3 3v16a2 2 0 0 0 2 2h16" /> <rect x="15" y="5" width="4" height="12" rx="1" /> <rect x="7" y="8" width="4" height="9" rx="1" /></symbol>
+  <symbol id="i-settings" viewBox="0 0 24 24"><path d="M9.671 4.136a2.34 2.34 0 0 1 4.659 0 2.34 2.34 0 0 0 3.319 1.915 2.34 2.34 0 0 1 2.33 4.033 2.34 2.34 0 0 0 0 3.831 2.34 2.34 0 0 1-2.33 4.033 2.34 2.34 0 0 0-3.319 1.915 2.34 2.34 0 0 1-4.659 0 2.34 2.34 0 0 0-3.32-1.915 2.34 2.34 0 0 1-2.33-4.033 2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915" /> <circle cx="12" cy="12" r="3" /></symbol>
+  <symbol id="i-ingestion" viewBox="0 0 24 24"><path d="M12 13v8" /> <path d="M4 14.899A7 7 0 1 1 15.71 8h1.79a4.5 4.5 0 0 1 2.5 8.242" /> <path d="m8 17 4-4 4 4" /></symbol>
+  <symbol id="i-rates" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /> <path d="M16 8h-6a2 2 0 1 0 0 4h4a2 2 0 1 1 0 4H8" /> <path d="M12 18V6" /></symbol>
+  <symbol id="i-notices" viewBox="0 0 24 24"><path d="m22 7-8.991 5.727a2 2 0 0 1-2.009 0L2 7" /> <rect x="2" y="4" width="20" height="16" rx="2" /></symbol>
+  <symbol id="i-filing-preview" viewBox="0 0 24 24"><path d="M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z" /> <path d="M14 2v5a1 1 0 0 0 1 1h5" /> <circle cx="11.5" cy="14.5" r="2.5" /> <path d="M13.3 16.3 15 18" /></symbol>
+  <symbol id="i-integration-health" viewBox="0 0 24 24"><path d="M22 12h-2.48a2 2 0 0 0-1.93 1.46l-2.35 8.36a.25.25 0 0 1-.48 0L9.24 2.18a.25.25 0 0 0-.48 0l-2.35 8.36A2 2 0 0 1 4.49 12H2" /></symbol>
+  <symbol id="i-finance" viewBox="0 0 24 24"><rect width="20" height="12" x="2" y="6" rx="2" /> <circle cx="12" cy="12" r="2" /> <path d="M6 12h.01M18 12h.01" /></symbol>
+  <symbol id="i-reconciliation" viewBox="0 0 24 24"><path d="M12 3v18" /> <path d="m19 8 3 8a5 5 0 0 1-6 0zV7" /> <path d="M3 7h1a17 17 0 0 0 8-2 17 17 0 0 0 8 2h1" /> <path d="m5 8 3 8a5 5 0 0 1-6 0zV7" /> <path d="M7 21h10" /></symbol>
+  <symbol id="i-quickbooks" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9"/><path d="M9 9a3 3 0 0 1 3-3v6"/><path d="M15 15a3 3 0 0 1-3 3v-6"/></symbol>
+  <symbol id="i-discrepancies" viewBox="0 0 24 24"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" /> <path d="M12 9v4" /> <path d="M12 17h.01" /></symbol>
+  <symbol id="i-period-close" viewBox="0 0 24 24"><path d="M8 2v4" /> <path d="M16 2v4" /> <rect width="18" height="18" x="3" y="4" rx="2" /> <path d="M3 10h18" /> <path d="m9 16 2 2 4-4" /></symbol>
+  <symbol id="i-client-dashboard" viewBox="0 0 24 24"><path d="m12 14 4-4" /> <path d="M3.34 19a10 10 0 1 1 17.32 0" /></symbol>
+  <symbol id="i-client-status" viewBox="0 0 24 24"><rect width="8" height="8" x="3" y="3" rx="2" /> <path d="M7 11v4a2 2 0 0 0 2 2h4" /> <rect width="8" height="8" x="13" y="13" rx="2" /></symbol>
+  <symbol id="i-client-registrations" viewBox="0 0 24 24"><path d="M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z" /> <path d="M14 2v5a1 1 0 0 0 1 1h5" /> <path d="M10 9H8" /> <path d="M16 13H8" /> <path d="M16 17H8" /></symbol>
+  <symbol id="i-client-licenses" viewBox="0 0 24 24"><path d="M16 10h2" /> <path d="M16 14h2" /> <path d="M6.17 15a3 3 0 0 1 5.66 0" /> <circle cx="9" cy="11" r="2" /> <rect x="2" y="5" width="20" height="14" rx="2" /></symbol>
+  <symbol id="i-client-notices" viewBox="0 0 24 24"><path d="m22 7-8.991 5.727a2 2 0 0 1-2.009 0L2 7" /> <rect x="2" y="4" width="20" height="16" rx="2" /></symbol>
+  <symbol id="i-client-renewals" viewBox="0 0 24 24"><path d="M21 12a9 9 0 1 1-9-9c2.52 0 4.93 1 6.74 2.74L21 8" /> <path d="M21 3v5h-5" /></symbol>
+  <symbol id="i-client-products" viewBox="0 0 24 24"><path d="M11 21.73a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73z" /> <path d="M12 22V12" /> <polyline points="3.29 7 12 12 20.71 7" /> <path d="m7.5 4.27 9 5.15" /></symbol>
+  <symbol id="i-client-distributors" viewBox="0 0 24 24"><path d="M14 18V6a2 2 0 0 0-2-2H4a2 2 0 0 0-2 2v11a1 1 0 0 0 1 1h2" /> <path d="M15 18H9" /> <path d="M19 18h2a1 1 0 0 0 1-1v-3.65a1 1 0 0 0-.22-.624l-3.48-4.35A1 1 0 0 0 17.52 8H14" /> <circle cx="17" cy="18" r="2" /> <circle cx="7" cy="18" r="2" /></symbol>
+  <symbol id="i-client-billing" viewBox="0 0 24 24"><path d="M13 16H8" /> <path d="M14 8H8" /> <path d="M16 12H8" /> <path d="M4 3a1 1 0 0 1 1-1 1.3 1.3 0 0 1 .7.2l.933.6a1.3 1.3 0 0 0 1.4 0l.934-.6a1.3 1.3 0 0 1 1.4 0l.933.6a1.3 1.3 0 0 0 1.4 0l.933-.6a1.3 1.3 0 0 1 1.4 0l.934.6a1.3 1.3 0 0 0 1.4 0l.933-.6A1.3 1.3 0 0 1 19 2a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1 1.3 1.3 0 0 1-.7-.2l-.933-.6a1.3 1.3 0 0 0-1.4 0l-.934.6a1.3 1.3 0 0 1-1.4 0l-.933-.6a1.3 1.3 0 0 0-1.4 0l-.933.6a1.3 1.3 0 0 1-1.4 0l-.934-.6a1.3 1.3 0 0 0-1.4 0l-.933.6a1.3 1.3 0 0 1-.7.2 1 1 0 0 1-1-1z" /></symbol>
+  <symbol id="i-client-documents" viewBox="0 0 24 24"><path d="M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z" /> <path d="M14 2v5a1 1 0 0 0 1 1h5" /> <path d="M10 9H8" /> <path d="M16 13H8" /> <path d="M16 17H8" /></symbol>
+  <symbol id="i-client-help" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /> <path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3" /> <path d="M12 17h.01" /></symbol>
+  <symbol id="i-back-to-admin" viewBox="0 0 24 24"><path d="m12 19-7-7 7-7" /> <path d="M19 12H5" /></symbol>
+  <symbol id="i-default" viewBox="0 0 24 24"><circle cx="12.1" cy="12.1" r="1" /></symbol>
+  <symbol id="i-lock-keyhole" viewBox="0 0 24 24"><circle cx="12" cy="16" r="1"/><rect x="3" y="10" width="18" height="12" rx="2"/><path d="M7 10V7a5 5 0 0 1 10 0v3"/></symbol>
+  <symbol id="i-liability-summary" viewBox="0 0 24 24"><rect width="16" height="20" x="4" y="2" rx="2"/><line x1="8" x2="16" y1="6" y2="6"/><line x1="16" x2="16" y1="14" y2="18"/><path d="M16 10h.01"/><path d="M12 10h.01"/><path d="M8 10h.01"/><path d="M12 14h.01"/><path d="M8 14h.01"/><path d="M12 18h.01"/><path d="M8 18h.01"/></symbol>
+  <symbol id="i-filing-tasks" viewBox="0 0 24 24"><path d="M13 5h8"/><path d="M13 12h8"/><path d="M13 19h8"/><path d="m3 17 2 2 4-4"/><path d="m3 7 2 2 4-4"/></symbol>
+  <symbol id="i-transactions" viewBox="0 0 24 24"><path d="M8 3 4 7l4 4"/><path d="M4 7h16"/><path d="m16 21 4-4-4-4"/><path d="M20 17H4"/></symbol>
+  <symbol id="i-import-history" viewBox="0 0 24 24"><path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/><path d="M12 7v5l4 2"/></symbol>
+  <symbol id="i-visual-form-editor" viewBox="0 0 24 24"><path d="M13 7 8.7 2.7a2.41 2.41 0 0 0-3.4 0L2.7 5.3a2.41 2.41 0 0 0 0 3.4L7 13"/><path d="m8 6 2-2"/><path d="m18 16 2-2"/><path d="m17 11 4.3 4.3c.94.94.94 2.46 0 3.4l-2.6 2.6c-.94.94-2.46.94-3.4 0L11 17"/><path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"/><path d="m15 5 4 4"/></symbol>
+  <!-- ui: general-purpose interface glyphs (search, actions, disclosure, status) -->
+  <symbol id="i-chevron-down" viewBox="0 0 24 24"><path d="m6 9 6 6 6-6" /></symbol>
+  <symbol id="i-chevron-up" viewBox="0 0 24 24"><path d="m18 15-6-6-6 6" /></symbol>
+  <symbol id="i-chevron-left" viewBox="0 0 24 24"><path d="m15 18-6-6 6-6" /></symbol>
+  <symbol id="i-chevron-right" viewBox="0 0 24 24"><path d="m9 18 6-6-6-6" /></symbol>
+  <symbol id="i-arrow-left" viewBox="0 0 24 24"><path d="m12 19-7-7 7-7" /> <path d="M19 12H5" /></symbol>
+  <symbol id="i-arrow-right" viewBox="0 0 24 24"><path d="M5 12h14" /> <path d="m12 5 7 7-7 7" /></symbol>
+  <symbol id="i-sort" viewBox="0 0 24 24"><path d="m21 16-4 4-4-4" /> <path d="M17 20V4" /> <path d="m3 8 4-4 4 4" /> <path d="M7 4v16" /></symbol>
+  <symbol id="i-search" viewBox="0 0 24 24"><path d="m21 21-4.34-4.34" /> <circle cx="11" cy="11" r="8" /></symbol>
+  <symbol id="i-plus" viewBox="0 0 24 24"><path d="M5 12h14" /> <path d="M12 5v14" /></symbol>
+  <symbol id="i-x" viewBox="0 0 24 24"><path d="M18 6 6 18" /> <path d="m6 6 12 12" /></symbol>
+  <symbol id="i-check" viewBox="0 0 24 24"><path d="M20 6 9 17l-5-5" /></symbol>
+  <symbol id="i-copy" viewBox="0 0 24 24"><rect width="14" height="14" x="8" y="8" rx="2" ry="2" /> <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></symbol>
+  <symbol id="i-pencil" viewBox="0 0 24 24"><path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z" /> <path d="m15 5 4 4" /></symbol>
+  <symbol id="i-trash" viewBox="0 0 24 24"><path d="M10 11v6" /> <path d="M14 11v6" /> <path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6" /> <path d="M3 6h18" /> <path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2" /></symbol>
+  <symbol id="i-download" viewBox="0 0 24 24"><path d="M12 15V3" /> <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /> <path d="m7 10 5 5 5-5" /></symbol>
+  <symbol id="i-upload" viewBox="0 0 24 24"><path d="M12 3v12" /> <path d="m17 8-5-5-5 5" /> <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /></symbol>
+  <symbol id="i-external-link" viewBox="0 0 24 24"><path d="M15 3h6v6" /> <path d="M10 14 21 3" /> <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" /></symbol>
+  <symbol id="i-filter" viewBox="0 0 24 24"><path d="M10 20a1 1 0 0 0 .553.895l2 1A1 1 0 0 0 14 21v-7a2 2 0 0 1 .517-1.341L21.74 4.67A1 1 0 0 0 21 3H3a1 1 0 0 0-.742 1.67l7.225 7.989A2 2 0 0 1 10 14z" /></symbol>
+  <symbol id="i-more" viewBox="0 0 24 24"><circle cx="12" cy="12" r="1" /> <circle cx="19" cy="12" r="1" /> <circle cx="5" cy="12" r="1" /></symbol>
+  <symbol id="i-refresh" viewBox="0 0 24 24"><path d="M21 12a9 9 0 1 1-9-9c2.52 0 4.93 1 6.74 2.74L21 8" /> <path d="M21 3v5h-5" /></symbol>
+  <symbol id="i-log-out" viewBox="0 0 24 24"><path d="m16 17 5-5-5-5" /> <path d="M21 12H9" /> <path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" /></symbol>
+  <symbol id="i-eye" viewBox="0 0 24 24"><path d="M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0" /> <circle cx="12" cy="12" r="3" /></symbol>
+  <symbol id="i-eye-off" viewBox="0 0 24 24"><path d="M10.733 5.076a10.744 10.744 0 0 1 11.205 6.575 1 1 0 0 1 0 .696 10.747 10.747 0 0 1-1.444 2.49" /> <path d="M14.084 14.158a3 3 0 0 1-4.242-4.242" /> <path d="M17.479 17.499a10.75 10.75 0 0 1-15.417-5.151 1 1 0 0 1 0-.696 10.75 10.75 0 0 1 4.446-5.143" /> <path d="m2 2 20 20" /></symbol>
+  <symbol id="i-info" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /> <path d="M12 16v-4" /> <path d="M12 8h.01" /></symbol>
+  <symbol id="i-alert-triangle" viewBox="0 0 24 24"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" /> <path d="M12 9v4" /> <path d="M12 17h.01" /></symbol>
+  <symbol id="i-check-circle" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /> <path d="m9 12 2 2 4-4" /></symbol>
+  <symbol id="i-x-circle" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /> <path d="m15 9-6 6" /> <path d="m9 9 6 6" /></symbol>
+  <symbol id="i-clock" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /> <path d="M12 6v6l4 2" /></symbol>
+  <symbol id="i-spinner" viewBox="0 0 24 24"><path d="M21 12a9 9 0 1 1-6.219-8.56" /></symbol>
+  <symbol id="i-package" viewBox="0 0 24 24"><path d="M11 21.73a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73z" /> <path d="M12 22V12" /> <polyline points="3.29 7 12 12 20.71 7" /> <path d="m7.5 4.27 9 5.15" /></symbol>
+  <symbol id="i-truck" viewBox="0 0 24 24"><path d="M14 18V6a2 2 0 0 0-2-2H4a2 2 0 0 0-2 2v11a1 1 0 0 0 1 1h2" /> <path d="M15 18H9" /> <path d="M19 18h2a1 1 0 0 0 1-1v-3.65a1 1 0 0 0-.22-.624l-3.48-4.35A1 1 0 0 0 17.52 8H14" /> <circle cx="17" cy="18" r="2" /> <circle cx="7" cy="18" r="2" /></symbol>
+  <symbol id="i-history" viewBox="0 0 24 24"><path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8" /> <path d="M3 3v5h5" /> <path d="M12 7v5l4 2" /></symbol>
+  <symbol id="i-folder" viewBox="0 0 24 24"><path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z" /></symbol>
+  <symbol id="i-chart-bar" viewBox="0 0 24 24"><path d="M3 3v16a2 2 0 0 0 2 2h16" /> <rect x="15" y="5" width="4" height="12" rx="1" /> <rect x="7" y="8" width="4" height="9" rx="1" /></symbol>
+  <symbol id="i-shield" viewBox="0 0 24 24"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z" /></symbol>
+  <symbol id="i-route" viewBox="0 0 24 24"><circle cx="6" cy="19" r="3" /> <path d="M9 19h8.5a3.5 3.5 0 0 0 0-7h-11a3.5 3.5 0 0 1 0-7H15" /> <circle cx="18" cy="5" r="3" /></symbol>
+  <symbol id="i-globe" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /> <path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20" /> <path d="M2 12h20" /></symbol>
+  <symbol id="i-users" viewBox="0 0 24 24"><path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2" /> <path d="M16 3.128a4 4 0 0 1 0 7.744" /> <path d="M22 21v-2a4 4 0 0 0-3-3.87" /> <circle cx="9" cy="7" r="4" /></symbol>
+  <symbol id="i-sliders" viewBox="0 0 24 24"><path d="M10 5H3" /> <path d="M12 19H3" /> <path d="M14 3v4" /> <path d="M16 17v4" /> <path d="M21 12h-9" /> <path d="M21 19h-5" /> <path d="M21 5h-7" /> <path d="M8 10v4" /> <path d="M8 12H3" /></symbol>
+  <symbol id="i-plug" viewBox="0 0 24 24"><path d="M12 22v-5" /> <path d="M15 8V2" /> <path d="M17 8a1 1 0 0 1 1 1v4a4 4 0 0 1-4 4h-4a4 4 0 0 1-4-4V9a1 1 0 0 1 1-1z" /> <path d="M9 8V2" /></symbol>
+</svg>

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@bevlogic/style-system",
+  "version": "0.1.0",
+  "description": "BevLogic shared design tokens, icon sprite, and brand mark. The single source of truth for consistent BevLogic UI.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BevLogic/style-system.git"
+  },
+  "files": [
+    "tokens.css",
+    "icons.svg",
+    "icons.json",
+    "brand-mark.svg",
+    "recipes",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    "./tokens.css": "./tokens.css",
+    "./icons.svg": "./icons.svg",
+    "./icons.json": "./icons.json",
+    "./brand-mark.svg": "./brand-mark.svg"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "bevlogic",
+    "style-guide"
+  ]
+}

package/recipes/app-shell.md

@@ -0,0 +1,178 @@
+# Recipe: App shell
+
+The canonical layout: **fixed navy left sidebar + sticky topbar + centered
+content**, a CSS grid. Requires `tokens.css` and `icons.svg`.
+
+## CSS (shared)
+
+```css
+.app {
+  display: grid;
+  grid-template-columns: var(--sidebar-width) 1fr;
+  min-height: 100vh;
+  transition: grid-template-columns 0.18s ease;
+}
+.app.sidebar-collapsed { grid-template-columns: var(--sidebar-collapsed-width) 1fr; }
+
+.sidebar {
+  background: var(--sidebar-bg);
+  color: var(--sidebar-fg);
+  padding: 18px 12px;
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  overflow: auto;
+  z-index: 20;
+}
+.brand {
+  font-weight: var(--fw-semibold);
+  font-size: 16px;
+  padding: 6px 10px 18px;
+  letter-spacing: 0.3px;
+  display: flex;
+  align-items: center;
+  gap: var(--space-1);
+}
+.brand .brand-dot {
+  width: 20px; height: 20px;
+  background: var(--accent);
+  -webkit-mask: var(--brand-mark) center / contain no-repeat;
+  mask: var(--brand-mark) center / contain no-repeat;
+}
+
+.nav-section {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.8px;
+  color: var(--sidebar-fg-faint);
+  padding: 14px 10px 6px;
+}
+.nav { list-style: none; padding: 0; margin: 0; }
+.nav li a {
+  display: flex;
+  align-items: center;
+  gap: 11px;
+  padding: var(--space-1) 10px;
+  border-radius: var(--radius-sm);
+  color: var(--sidebar-fg-muted);
+  font-size: 13.5px;
+  transition: background 0.12s ease;
+}
+.nav li a:hover { background: var(--sidebar-hover-bg); color: var(--sidebar-fg-strong); }
+.nav li a.active { background: var(--sidebar-active-bg); color: var(--sidebar-fg-strong); }
+.nav .nav-icon { display: inline-grid; place-items: center; width: 22px; height: 22px; flex: 0 0 22px; }
+.nav .nav-icon svg {
+  width: 19px; height: 19px;
+  stroke: currentColor; fill: none;
+  stroke-width: 1.75; stroke-linecap: round; stroke-linejoin: round;
+}
+
+.topbar {
+  background: var(--surface);
+  border-bottom: 1px solid var(--border);
+  padding: 10px var(--space-3);
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  position: sticky;
+  top: 0;
+  z-index: 10;
+}
+
+.content { padding: var(--space-3); max-width: 1280px; width: 100%; margin: 0 auto; }
+.page-header { display: flex; align-items: flex-start; justify-content: space-between; margin-bottom: 18px; gap: var(--space-2); }
+.page-title { font-size: var(--fs-title); font-weight: var(--fw-semibold); margin: 0 0 var(--space-half); }
+.page-sub { font-size: var(--fs-sm); color: var(--text-muted); margin: 0; }
+```
+
+## Markup
+
+**React** - data-driven nav.
+```tsx
+const NAV = [
+  { label: 'Filing tasks', to: '/', icon: 'i-filing-tasks' },
+  { label: 'Transactions', to: '/transactions', icon: 'i-transactions' },
+];
+
+export function Shell({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="app">
+      <aside className="sidebar">
+        <div className="brand"><span className="brand-dot" />BevLogic</div>
+        <div className="nav-section">Returns</div>
+        <ul className="nav">
+          {NAV.map(n => (
+            <li key={n.to}>
+              <NavLink to={n.to} className={({ isActive }) => isActive ? 'active' : ''}>
+                <span className="nav-icon"><svg><use href={`/icons.svg#${n.icon}`} /></svg></span>
+                <span className="nav-label-text">{n.label}</span>
+              </NavLink>
+            </li>
+          ))}
+        </ul>
+      </aside>
+      <div className="main">
+        <header className="topbar">{/* search, user menu */}</header>
+        <main className="content">{children}</main>
+      </div>
+    </div>
+  );
+}
+```
+
+**Static HTML**
+```html
+<div class="app">
+  <aside class="sidebar">
+    <div class="brand"><span class="brand-dot"></span>BevLogic</div>
+    <div class="nav-section">Rates</div>
+    <ul class="nav">
+      <li><a href="/rates" class="active">
+        <span class="nav-icon"><svg><use href="/icons.svg#i-rates" /></svg></span>
+        <span class="nav-label-text">Fixed rates</span>
+      </a></li>
+    </ul>
+  </aside>
+  <div class="main">
+    <header class="topbar"><!-- search / user --></header>
+    <main class="content">
+      <div class="page-header">
+        <div><h1 class="page-title">Fixed rates</h1><p class="page-sub">13 states</p></div>
+      </div>
+      <!-- page content -->
+    </main>
+  </div>
+</div>
+```
+
+**PHP** - for a server-rendered app. Point the shell's tokens at these values
+(navy `--sidebar-bg`, accent `--accent`) and render the nav from your own data.
+```php
+<div class="app">
+  <aside class="sidebar">
+    <div class="brand"><span class="brand-dot"></span>BevLogic</div>
+    <?php foreach ($sections as $section): ?>
+      <div class="nav-section"><?= htmlspecialchars($section['label']) ?></div>
+      <ul class="nav">
+        <?php foreach ($section['items'] as $item): ?>
+          <li><a href="<?= $item['href'] ?>" class="<?= $item['active'] ? 'active' : '' ?>">
+            <span class="nav-icon"><svg><use href="/icons.svg#<?= $item['icon'] ?>" /></svg></span>
+            <span class="nav-label-text"><?= htmlspecialchars($item['label']) ?></span>
+          </a></li>
+        <?php endforeach; ?>
+      </ul>
+    <?php endforeach; ?>
+  </aside>
+  <div class="main">
+    <header class="topbar"><!-- .bev-page-header equivalent --></header>
+    <main class="content"><?= $body ?></main>
+  </div>
+</div>
+```
+
+## Notes
+- Sidebar keeps its own `--sidebar-*` tokens so it stays dark regardless of body theme.
+- Collapsed mode (`.app.sidebar-collapsed`, 64px icon-only rail with hover tooltips) can be layered on; not reproduced here to keep the recipe focused.
+- If you are only reskinning the shell, page bodies inside `.content` can keep their existing markup; align the shell first, content later.

package/recipes/badge-pill.md

@@ -0,0 +1,80 @@
+# Recipe: Badge & Chip
+
+`.badge` — a status pill with a leading colored dot. `.chip` — a small
+labeled token. Requires `tokens.css`.
+
+## CSS (shared)
+
+```css
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-half);
+  padding: 2px var(--space-1);
+  border-radius: var(--radius-pill);
+  font-size: var(--fs-label);
+  font-weight: var(--fw-medium);
+  background: var(--primary-soft);
+  color: var(--text);
+}
+.badge::before {
+  content: '';
+  width: 6px; height: 6px;
+  border-radius: 50%;
+  background: var(--text-faint);
+}
+.badge.success { background: var(--success-soft); color: var(--success); }
+.badge.success::before { background: var(--success); }
+.badge.warning { background: var(--warning-soft); color: var(--warning); }
+.badge.warning::before { background: var(--warning); }
+.badge.danger  { background: var(--danger-soft);  color: var(--danger); }
+.badge.danger::before { background: var(--danger); }
+.badge.info    { background: var(--info-soft);    color: var(--info); }
+.badge.info::before { background: var(--info); }
+.badge.accent  { background: var(--accent-soft);  color: var(--accent); }
+.badge.accent::before { background: var(--accent); }
+.badge.plain::before { display: none; }
+
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-half);
+  padding: 2px var(--space-1) 2px var(--space-half);
+  border-radius: var(--radius-pill);
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  font-size: var(--fs-meta);
+}
+```
+
+## Markup
+
+**React**
+```tsx
+type BadgeTone = 'success' | 'warning' | 'danger' | 'info' | 'accent' | 'plain';
+
+export function Badge({ tone, children }: { tone?: BadgeTone; children: React.ReactNode }) {
+  return <span className={`badge ${tone ?? ''}`}>{children}</span>;
+}
+// <Badge tone="success">Filed</Badge>
+```
+
+**Static HTML**
+```html
+<span class="badge success">Filed</span>
+<span class="badge warning">Due soon</span>
+<span class="badge danger">Failed</span>
+<span class="chip">CA · Sales</span>
+```
+
+**PHP**
+```php
+<?php function bev_badge(string $label, string $tone = ''): string {
+    return '<span class="badge ' . htmlspecialchars($tone) . '">' . htmlspecialchars($label) . '</span>';
+} ?>
+<?= bev_badge('Filed', 'success') ?>
+```
+
+## Notes
+- Tone maps to meaning: success/warning/danger/info per the status tokens. Don't pick a tone for looks.
+- `.plain` drops the dot for non-status labels.

package/recipes/button.md

@@ -0,0 +1,88 @@
+# Recipe: Button
+
+`.btn` with `primary` / `ghost` / `sm` modifiers. Requires `tokens.css`.
+
+## CSS (shared — token-based, identical across stacks)
+
+```css
+.btn {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-half);
+  padding: 7px 13px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-strong);
+  background: var(--surface);
+  font: inherit;
+  font-size: var(--fs-sm);
+  cursor: pointer;
+  color: var(--text);
+  transition: background 0.12s ease, border-color 0.12s ease;
+}
+.btn:hover { background: var(--surface-2); border-color: var(--text-faint); }
+
+.btn.primary { background: var(--accent); color: var(--text-on-accent); border-color: var(--accent); }
+.btn.primary:hover { background: var(--accent-hover); border-color: var(--accent-hover); }
+
+/* Gradient accent: the single headline action on a screen (hero, onboarding,
+   empty state). The flat .primary stays the default for ordinary views. */
+.btn.accent { background: var(--grad-accent); color: var(--text-on-accent); border-color: transparent; }
+.btn.accent:hover { background: var(--grad-accent-deep); border-color: transparent; }
+
+.btn.ghost { background: transparent; border-color: transparent; color: var(--text-muted); }
+.btn.ghost:hover { background: var(--primary-soft); color: var(--text); }
+
+.btn.sm { padding: var(--space-half) 9px; font-size: var(--fs-meta); }
+```
+
+## Markup
+
+**React**
+```tsx
+type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  variant?: 'default' | 'primary' | 'accent' | 'ghost';
+  size?: 'default' | 'sm';
+};
+
+export function Button({ variant = 'default', size = 'default', className = '', ...props }: ButtonProps) {
+  const cls = ['btn', variant !== 'default' && variant, size === 'sm' && 'sm', className]
+    .filter(Boolean).join(' ');
+  return <button className={cls} {...props} />;
+}
+// <Button variant="primary">New return</Button>
+```
+
+**Static HTML**
+```html
+<button class="btn primary">New return</button>
+<button class="btn accent">Start filing</button>
+<button class="btn">Cancel</button>
+<button class="btn ghost sm">Dismiss</button>
+```
+
+**PHP**
+```php
+<?php function bev_button(string $label, string $variant = '', string $size = ''): string {
+    $cls = trim('btn ' . $variant . ' ' . $size);
+    return '<button class="' . htmlspecialchars($cls) . '">' . htmlspecialchars($label) . '</button>';
+} ?>
+<?= bev_button('New return', 'primary') ?>
+```
+
+## When to use which
+
+- **Accent** (gradient) = the single headline action on a screen. The one thing
+  you want the user to do next: onboarding, empty state, "start a filing". One
+  per screen, so it stays the obvious next step.
+- **Primary** (solid accent) = the main action in ordinary views. One per view:
+  toolbars, forms, dialog confirm. The default for the important action when
+  there's no headline moment.
+- **Default** = secondary actions beside a primary. Cancel, back, "save draft".
+  Neutral, doesn't compete with the main action.
+- **Ghost** = low-emphasis actions in dense UI. Table row actions, dismiss,
+  toolbar overflow. Quiet by design.
+- **Small** (`sm`) = a size modifier, not a variant. Combine with any of the above
+  (`btn primary sm`) for tight rows: table cells, inline toolbars.
+
+Rule of thumb per view: at most one accent OR one primary as the leading action,
+never both competing; default and ghost carry everything else.

package/recipes/card.md

@@ -0,0 +1,97 @@
+# Recipe: Card & Stat tile
+
+`.card` (surface container) + `.card-h` (header row), and the `.stat` KPI tile.
+Requires `tokens.css`.
+
+## CSS (shared)
+
+```css
+.card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: var(--space-2);
+  box-shadow: var(--shadow-sm);
+}
+.card-h {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 12px;
+}
+.card-h h3 { font-size: var(--fs-h); font-weight: var(--fw-semibold); margin: 0; color: var(--text); }
+.card-h .muted { font-size: var(--fs-meta); color: var(--text-muted); }
+
+/* Stat / KPI tile */
+.stat {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 14px var(--space-2);
+}
+.stat-label {
+  font-size: var(--fs-label);
+  text-transform: uppercase;
+  letter-spacing: 0.6px;
+  color: var(--text-muted);
+  margin-bottom: var(--space-half);
+}
+.stat-value { font-size: var(--fs-stat); font-weight: var(--fw-semibold); letter-spacing: -0.2px; }
+.stat-delta { font-size: var(--fs-label); margin-top: var(--space-half); color: var(--text-muted); }
+.stat-delta.up { color: var(--success); }
+.stat-delta.down { color: var(--danger); }
+```
+
+## Markup
+
+**React**
+```tsx
+export function Card({ title, action, children }: {
+  title?: string; action?: React.ReactNode; children: React.ReactNode;
+}) {
+  return (
+    <div className="card">
+      {title && <div className="card-h"><h3>{title}</h3>{action}</div>}
+      {children}
+    </div>
+  );
+}
+
+export function Stat({ label, value, delta, dir }: {
+  label: string; value: string; delta?: string; dir?: 'up' | 'down';
+}) {
+  return (
+    <div className="stat">
+      <div className="stat-label">{label}</div>
+      <div className="stat-value">{value}</div>
+      {delta && <div className={`stat-delta ${dir ?? ''}`}>{delta}</div>}
+    </div>
+  );
+}
+```
+
+**Static HTML**
+```html
+<div class="card">
+  <div class="card-h"><h3>Filing tasks</h3><span class="muted">This week</span></div>
+  <!-- content -->
+</div>
+
+<div class="stat">
+  <div class="stat-label">Open returns</div>
+  <div class="stat-value">42</div>
+  <div class="stat-delta up">+6 vs last week</div>
+</div>
+```
+
+**PHP**
+```php
+<div class="card">
+  <div class="card-h"><h3><?= htmlspecialchars($title) ?></h3></div>
+  <?= $body /* trusted markup */ ?>
+</div>
+```
+
+## Notes
+- Group stat tiles in a 4-up grid that collapses to 2-up under 1000px.
+- Card padding is `--space-2` (16px) for new work; older screens use 18px — fine to leave, don't churn.

package/recipes/input.md

@@ -0,0 +1,87 @@
+# Recipe: Input & Search field
+
+A text input primitive plus the topbar `.search` field. Requires `tokens.css`.
+
+> This `.input` primitive codifies a consistent standalone field for new work,
+> alongside the topbar `.search` container.
+
+## CSS (shared)
+
+```css
+.input {
+  width: 100%;
+  padding: 7px 12px;
+  font: inherit;
+  font-size: var(--fs-sm);
+  color: var(--text);
+  background: var(--surface);
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius-sm);
+  outline: none;
+  transition: border-color 0.12s ease, box-shadow 0.12s ease;
+}
+.input::placeholder { color: var(--text-faint); }
+.input:focus { border-color: var(--accent); box-shadow: 0 0 0 3px var(--focus-ring); }
+.input:disabled { background: var(--surface-2); color: var(--text-faint); cursor: not-allowed; }
+
+/* Labeled field wrapper */
+.field { display: flex; flex-direction: column; gap: var(--space-half); }
+.field label { font-size: var(--fs-meta); color: var(--text-muted); font-weight: var(--fw-medium); }
+.field-error { font-size: var(--fs-meta); color: var(--danger); }
+
+/* Topbar search (icon + borderless input in a filled container) */
+.search {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  gap: var(--space-1);
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 7px 12px;
+  max-width: 520px;
+}
+.search input { flex: 1; border: none; background: transparent; outline: none; font: inherit; color: var(--text); }
+```
+
+## Markup
+
+**React**
+```tsx
+export function Field({ label, error, ...props }: {
+  label?: string; error?: string;
+} & React.InputHTMLAttributes<HTMLInputElement>) {
+  return (
+    <div className="field">
+      {label && <label>{label}</label>}
+      <input className="input" {...props} />
+      {error && <span className="field-error">{error}</span>}
+    </div>
+  );
+}
+```
+
+**Static HTML**
+```html
+<div class="field">
+  <label for="ein">EIN</label>
+  <input class="input" id="ein" type="text" placeholder="00-0000000" />
+</div>
+
+<div class="search">
+  <svg class="icon" aria-hidden="true"><use href="/icons.svg#i-search" /></svg>
+  <input type="search" placeholder="Search…" />
+  <span class="kbd">⌘K</span>
+</div>
+```
+
+**PHP**
+```php
+<div class="field">
+  <label for="<?= $id ?>"><?= htmlspecialchars($label) ?></label>
+  <input class="input" id="<?= $id ?>" name="<?= $id ?>" value="<?= htmlspecialchars($value) ?>" />
+</div>
+```
+
+## Notes
+- Focus ring is `--accent` border + `--focus-ring` glow, consistent across all inputs.

package/recipes/table.md

@@ -0,0 +1,100 @@
+# Recipe: Data table
+
+`table.data` — the dense data table with uppercase headers and hover rows.
+Requires `tokens.css`.
+
+## CSS (shared)
+
+```css
+table.data {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: var(--fs-sm);
+}
+table.data th {
+  text-align: left;
+  padding: 9px 12px;
+  font-weight: var(--fw-semibold);
+  font-size: var(--fs-label);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  color: var(--text-muted);
+  background: var(--surface-2);
+  border-bottom: 1px solid var(--border);
+}
+table.data td {
+  padding: 10px 12px;
+  border-bottom: 1px solid var(--border);
+  vertical-align: middle;
+}
+table.data tr:last-child td { border-bottom: none; }
+table.data tr:hover td { background: var(--surface-2); }
+table.data .row-link td:first-child { font-weight: var(--fw-medium); }
+
+/* Right-align + tabular figures for numeric columns */
+table.data td.numeric,
+table.data th.numeric { text-align: right; font-variant-numeric: tabular-nums; }
+```
+
+## Markup
+
+**React**
+```tsx
+export function DataTable<T>({ columns, rows, keyOf }: {
+  columns: { key: keyof T; label: string; numeric?: boolean }[];
+  rows: T[];
+  keyOf: (row: T) => string;
+}) {
+  return (
+    <table className="data">
+      <thead><tr>
+        {columns.map(c => (
+          <th key={String(c.key)} className={c.numeric ? 'numeric' : ''}>{c.label}</th>
+        ))}
+      </tr></thead>
+      <tbody>
+        {rows.map(row => (
+          <tr key={keyOf(row)}>
+            {columns.map(c => (
+              <td key={String(c.key)} className={c.numeric ? 'numeric' : ''}>{String(row[c.key])}</td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+```
+
+**Static HTML**
+```html
+<table class="data">
+  <thead>
+    <tr><th>Jurisdiction</th><th>Period</th><th class="numeric">Liability</th><th>Status</th></tr>
+  </thead>
+  <tbody>
+    <tr class="row-link">
+      <td>California</td><td>2026-Q2</td><td class="numeric">$12,480.00</td>
+      <td><span class="badge success">Filed</span></td>
+    </tr>
+  </tbody>
+</table>
+```
+
+**PHP**
+```php
+<table class="data">
+  <thead><tr><?php foreach ($cols as $c): ?>
+    <th class="<?= !empty($c['numeric']) ? 'numeric' : '' ?>"><?= htmlspecialchars($c['label']) ?></th>
+  <?php endforeach; ?></tr></thead>
+  <tbody><?php foreach ($rows as $r): ?>
+    <tr><?php foreach ($cols as $c): ?>
+      <td class="<?= !empty($c['numeric']) ? 'numeric' : '' ?>"><?= htmlspecialchars($r[$c['key']]) ?></td>
+    <?php endforeach; ?></tr>
+  <?php endforeach; ?></tbody>
+</table>
+```
+
+## Notes
+- Money/count columns get `.numeric` (right-aligned, tabular figures) so digits line up.
+- Status cells use a `.badge` (see `recipes/badge-pill.md`), not colored text.

package/tokens.css

@@ -0,0 +1,167 @@
+/*
+ * @bevlogic/style-system — tokens.css
+ *
+ * The single source of truth for BevLogic UI design tokens.
+ *
+ * Consume this file, don't fork its values. If you need a value that isn't
+ * here, that's a signal to add a token, not to hardcode a hex/px in your app.
+ *
+ * Light theme only for now; dark-mode tokens are parked until dark mode is
+ * formally on the roadmap.
+ */
+
+:root {
+  color-scheme: light;
+
+  /* ---- Layout rails ---- */
+  --sidebar-width: 240px;
+  --sidebar-collapsed-width: 64px;
+
+  /* ---- Surfaces & neutrals ---- */
+  --bg: #f5f6f8;
+  --surface: #ffffff;
+  --surface-2: #fafbfc;
+  --surface-raised: #ffffff;
+  --border: #e4e7eb;
+  --border-strong: #cbd2d9;
+
+  /* ---- Text ---- */
+  --text: #1f2933;
+  --text-muted: #616e7c;
+  --text-faint: #9aa5b1;
+  --text-on-accent: #ffffff;
+
+  /* ---- Brand ---- */
+  --primary: #2d3a4f;          /* BevLogic navy */
+  --primary-deep: #232e40;     /* darker navy: gradient depth (was inline in the hero) */
+  --primary-deeper: #1f2933;   /* deepest navy: hero/panel floor */
+  --primary-soft: #eef1f6;
+  --accent: #5a6cff;           /* indigo/periwinkle: the interactive accent */
+  --accent-soft: #ecefff;
+  --accent-hover: #4456e6;
+  --accent-gradient-2: #8b9bff;
+
+  /* Brand mark: the BevLogic sunburst, as a CSS mask value. Paint it by
+     setting a color and this mask, e.g. .brand-dot { background: var(--accent);
+     mask: var(--brand-mark) center/contain no-repeat; }. Source: brand-mark.svg. */
+  --brand-mark: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20100%20100%22%20fill%3D%22%23000%22%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%280%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%2818%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%2836%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%2854%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%2872%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%2890%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28108%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28126%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28144%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28162%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28180%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28198%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28216%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28234%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28252%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28270%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28288%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28306%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28324%2050%2050%29%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2217%22%20rx%3D%223.2%22%20ry%3D%227%22%20transform%3D%22rotate%28342%2050%2050%29%22%2F%3E%3C%2Fsvg%3E");
+
+  /* ---- Gradients (derived from the palette above; consume by name, don't
+     re-roll a linear-gradient() inline). Kept restrained on purpose: navy
+     family for depth, indigo reserved for small accent surfaces. ---- */
+
+  /* Sidebar rail: navy base with a faint indigo bloom top-left. */
+  --grad-sidebar:
+    radial-gradient(120% 60% at 20% 0%, rgba(90, 108, 255, 0.20), transparent 60%),
+    linear-gradient(180deg, var(--primary), #202a3a);
+  /* Sidebar right edge, as a border-image: indigo fading to nothing downward.
+     Use with: border-right: 2px solid transparent; border-image: var(--grad-sidebar-edge) 1; */
+  --grad-sidebar-edge:
+    linear-gradient(180deg, var(--accent-gradient-2), var(--accent) 45%, transparent);
+
+  /* Brand accent: small pop surfaces only (marks, active accents, progress, buttons). */
+  --grad-accent:        linear-gradient(135deg, var(--accent), var(--accent-gradient-2));
+  --grad-accent-deep:   linear-gradient(135deg, var(--accent-hover), var(--accent));
+  --grad-brand-bridge:  linear-gradient(135deg, var(--primary), var(--accent));
+
+  /* Surface washes: barely-there panel/page backgrounds. */
+  --grad-surface:       linear-gradient(180deg, var(--surface), var(--bg));
+  --grad-surface-cool:  linear-gradient(160deg, var(--surface-2), var(--primary-soft));
+  --grad-accent-haze:   radial-gradient(100% 90% at 100% 0%, var(--accent-soft), transparent 55%);
+
+  /* Hero / feature panels: dark, same navy family as the sidebar. */
+  --grad-hero:
+    radial-gradient(80% 120% at 100% 0%, rgba(139, 155, 255, 0.28), transparent 50%),
+    radial-gradient(70% 110% at 0% 100%, rgba(90, 108, 255, 0.16), transparent 55%),
+    linear-gradient(135deg, var(--primary), var(--primary-deeper));
+  --grad-hero-spotlight:
+    radial-gradient(120% 80% at 50% -20%, rgba(90, 108, 255, 0.30), transparent 60%),
+    var(--primary-deep);
+
+  /* Status soft tints: optional dimension for banner/callout cards. */
+  --grad-status-success: linear-gradient(180deg, #eafaf3, var(--success-soft));
+  --grad-status-warning: linear-gradient(180deg, #fff7e6, var(--warning-soft));
+  --grad-status-danger:  linear-gradient(180deg, #fdecec, var(--danger-soft));
+  --grad-status-info:    linear-gradient(180deg, #eef5ff, var(--info-soft));
+
+  /* ---- Semantic status (each has a -soft background tint) ---- */
+  --success: #137752;   --success-soft: #def7ec;
+  --warning: #b54708;   --warning-soft: #fef3c7;
+  --danger:  #9b1c1c;   --danger-soft:  #fde2e2;
+  --info:    #1c64f2;   --info-soft:    #e1effe;
+
+  /* ---- Sidebar (own tokens: stays visually dark regardless of body theme) ---- */
+  --sidebar-bg: #2d3a4f;
+  --sidebar-fg: #e4e7eb;
+  --sidebar-fg-muted: #cbd2d9;
+  --sidebar-fg-faint: #9aa5b1;
+  --sidebar-fg-strong: #ffffff;
+  --sidebar-hover-bg: rgba(255, 255, 255, 0.06);
+  --sidebar-active-bg: rgba(255, 255, 255, 0.1);
+  --sidebar-border: rgba(255, 255, 255, 0.15);
+  --sidebar-border-soft: rgba(255, 255, 255, 0.08);
+  --sidebar-divider: rgba(255, 255, 255, 0.12);
+  --sidebar-badge-muted-bg: rgba(255, 255, 255, 0.18);
+  --sidebar-tooltip-bg: #1f2933;
+  --sidebar-tooltip-fg: #ffffff;
+
+  /* ---- Overlays / focus ---- */
+  --backdrop: rgba(20, 30, 50, 0.32);
+  --backdrop-soft: rgba(20, 30, 50, 0.28);
+  --backdrop-strong: rgba(20, 30, 50, 0.4);
+  --focus-ring: rgba(90, 108, 255, 0.35);
+  --client-body-bg: #f9fafb;
+
+  /* ---- Radii ---- */
+  --radius: 8px;
+  --radius-sm: 4px;
+  --radius-pill: 999px;
+
+  /* ---- Shadows ---- */
+  --shadow-sm: 0 1px 2px rgba(20, 30, 50, 0.05);
+  --shadow: 0 4px 14px rgba(20, 30, 50, 0.08);
+  --shadow-lg: 0 12px 28px rgba(20, 30, 50, 0.14);
+  --shadow-tooltip: 0 8px 22px rgba(0, 0, 0, 0.24);
+
+  /* ---- Fonts ---- */
+  --font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, sans-serif;
+  --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+
+  /*
+   * ===================================================================
+   * ADDITIONS — codified here, not present in the source apps yet.
+   * The apps hardcode these values inline; the style guide formalizes
+   * them so new work has named tokens to reach for.
+   * ===================================================================
+   */
+
+  /* ---- Spacing scale (8px grid — prefer multiples of 8) ----
+     --space-half is a deliberate escape hatch for genuinely tight cases
+     (icon gaps, hairline insets). It is NOT a normal step — reach for the
+     8-based steps first. */
+  --space-half: 4px;
+  --space-1: 8px;
+  --space-2: 16px;
+  --space-3: 24px;
+  --space-4: 32px;
+  --space-5: 48px;
+  --space-6: 64px;
+
+  /* ---- Type scale (the de-facto sizes across the apps, now named) ---- */
+  --fs-title: 22px;   /* page titles, detail headers */
+  --fs-stat: 24px;    /* KPI / stat values */
+  --fs-h: 14px;       /* card / section headings */
+  --fs-body: 14px;    /* base body */
+  --fs-sm: 13px;      /* dense tables, secondary body */
+  --fs-meta: 12.5px;  /* meta, captions */
+  --fs-label: 11.5px; /* uppercase eyebrow labels */
+
+  /* ---- Font weights ---- */
+  --fw-regular: 400;
+  --fw-medium: 500;
+  --fw-semibold: 600;
+  --fw-bold: 700;
+
+  /* ---- Line height ---- */
+  --lh-base: 1.5;
+}