@syncedco/flow 0.2.0 → 0.3.1

package/components.css

@@ -432,6 +432,16 @@
     to { transform: translateX(-50%); }
   }
 
+  @media (prefers-reduced-motion: reduce) {
+    :where(.sf-button:hover, .sf-card--interactive:hover) {
+      transform: none;
+    }
+
+    .sf-marquee__track {
+      animation: none;
+    }
+  }
+
   .sf-command-list {
     display: grid;
     font-family: var(--sf-font-mono);
@@ -837,7 +847,7 @@
   }
 
   .sf-filter-bar {
-    align-items: end;
+    align-items: var(--sf-filter-bar-align, center);
     background: var(--sf-colour-surface);
     border: 1px solid var(--sf-colour-border);
     border-radius: var(--sf-radius-panel);
@@ -885,6 +895,76 @@
     --sf-data-table-padding-inline: var(--sf-space-xs);
   }
 
+  .sf-data-table :where(th button, .sf-table-sort) {
+    align-items: center;
+    color: inherit;
+    display: inline-flex;
+    font: inherit;
+    font-weight: inherit;
+    gap: var(--sf-space-3xs);
+    padding: 0;
+  }
+
+  .sf-data-table :where(th button, .sf-table-sort)[aria-sort]::after {
+    color: var(--sf-colour-subtle);
+    content: "\2195";
+    font-size: var(--sf-step--2);
+  }
+
+  .sf-data-table :where(th button, .sf-table-sort)[aria-sort="ascending"]::after { content: "\2191"; }
+  .sf-data-table :where(th button, .sf-table-sort)[aria-sort="descending"]::after { content: "\2193"; }
+
+  .sf-data-table tr[data-clickable="true"] {
+    cursor: pointer;
+  }
+
+  .sf-data-table tr[data-clickable="true"]:focus-within {
+    outline: 0.125rem solid var(--sf-colour-ring);
+    outline-offset: -0.125rem;
+  }
+
+  @container (max-width: 38rem) {
+    .sf-table-wrap[data-view="cards"] {
+      border: 0;
+      overflow: visible;
+    }
+
+    .sf-table-wrap[data-view="cards"] .sf-data-table,
+    .sf-table-wrap[data-view="cards"] .sf-data-table :where(thead, tbody, tr, th, td) {
+      display: block;
+      min-inline-size: 0;
+    }
+
+    .sf-table-wrap[data-view="cards"] .sf-data-table thead {
+      display: none;
+    }
+
+    .sf-table-wrap[data-view="cards"] .sf-data-table tr {
+      background: var(--sf-colour-surface);
+      border: 1px solid var(--sf-colour-border);
+      border-radius: var(--sf-radius-panel);
+      margin-block-end: var(--sf-space-xs);
+      padding: var(--sf-space-xs);
+    }
+
+    .sf-table-wrap[data-view="cards"] .sf-data-table td {
+      align-items: center;
+      border: 0;
+      display: flex;
+      gap: var(--sf-space-s);
+      justify-content: space-between;
+      padding-block: var(--sf-space-2xs);
+      padding-inline: 0;
+    }
+
+    .sf-table-wrap[data-view="cards"] .sf-data-table td::before {
+      color: var(--sf-colour-muted);
+      content: attr(data-label);
+      font-size: var(--sf-step--1);
+      font-weight: 800;
+    }
+  }
+
   .sf-status {
     align-items: center;
     background: var(--sf-status-bg, var(--sf-colour-surface-alt));
@@ -900,6 +980,12 @@
     padding-inline: .7em;
   }
 
+  .sf-status[data-size="sm"] {
+    font-size: var(--sf-step--2);
+    min-block-size: 1.35rem;
+    padding-inline: .55em;
+  }
+
   .sf-status::before {
     background: currentColor;
     block-size: .42em;
@@ -908,6 +994,10 @@
     inline-size: .42em;
   }
 
+  :where(.sf-status[data-dot="false"], .sf-status--label)::before {
+    content: none;
+  }
+
   .sf-status[data-tone="success"] {
     --sf-status-bg: var(--sf-colour-success-soft);
     --sf-status-border: color-mix(in oklch, var(--sf-colour-success) 34%, transparent);
@@ -1055,6 +1145,13 @@
     gap: var(--sf-form-gap, var(--sf-space-s-m));
   }
 
+  .sf-form[data-density="compact"],
+  .sf-field[data-density="compact"] {
+    --sf-form-gap: var(--sf-space-xs);
+    --sf-input-block-size: 2.25rem;
+    --sf-input-padding-inline: var(--sf-space-xs);
+  }
+
   .sf-fieldset {
     border: 1px solid var(--sf-colour-border);
     border-radius: var(--sf-radius-panel);
@@ -1120,6 +1217,45 @@
     transition: background-color var(--sf-duration-fast) var(--sf-ease-standard), border-color var(--sf-duration-fast) var(--sf-ease-standard), box-shadow var(--sf-duration-fast) var(--sf-ease-standard);
   }
 
+  .sf-search {
+    position: relative;
+  }
+
+  .sf-search::before {
+    block-size: .75em;
+    border: 0.125em solid currentColor;
+    border-radius: var(--sf-radius-full);
+    color: var(--sf-colour-subtle);
+    content: "";
+    inline-size: .75em;
+    inset-block-start: 50%;
+    inset-inline-start: var(--sf-space-xs);
+    line-height: 1;
+    position: absolute;
+    transform: translateY(-58%);
+  }
+
+  .sf-search::after {
+    background: var(--sf-colour-subtle);
+    block-size: .125em;
+    content: "";
+    inline-size: .45em;
+    inset-block-start: 50%;
+    inset-inline-start: calc(var(--sf-space-xs) + .58em);
+    position: absolute;
+    transform: translateY(120%) rotate(45deg);
+    transform-origin: inline-start center;
+  }
+
+  .sf-search > .sf-input {
+    padding-inline-start: var(--sf-space-l);
+  }
+
+  .sf-help[data-density="compact"],
+  .sf-error[data-density="compact"] {
+    font-size: var(--sf-step--2);
+  }
+
   .sf-textarea {
     min-block-size: var(--sf-textarea-block-size, 8rem);
     padding-block: var(--sf-space-xs);
@@ -1240,7 +1376,7 @@
   .sf-dialog::backdrop,
   .sf-popover::backdrop,
   .sf-drawer::backdrop {
-    background: oklch(0% 0 0 / 0.48);
+    background: var(--sf-colour-backdrop);
   }
 
   .sf-dialog__header,
@@ -1266,6 +1402,11 @@
     justify-content: flex-end;
   }
 
+  .sf-dialog[data-layout="form"] .sf-dialog__body {
+    display: grid;
+    gap: var(--sf-space-s);
+  }
+
   .sf-popover,
   .sf-menu-popover,
   .sf-tooltip,
@@ -1291,6 +1432,7 @@
   :where(.sf-popover, .sf-menu-popover, .sf-tooltip, .sf-toast, .sf-banner, .sf-drawer):popover-open {
     display: grid;
     gap: var(--sf-space-xs);
+    z-index: var(--sf-z-overlay);
   }
 
   .sf-popover {
@@ -1319,6 +1461,16 @@
     background: var(--sf-colour-surface-alt);
   }
 
+  .sf-menu :where(a, button)[data-variant="danger"],
+  .sf-menu-popover :where(a, button)[data-variant="danger"] {
+    color: var(--sf-colour-danger);
+  }
+
+  .sf-menu :where(a, button)[data-variant="danger"]:hover,
+  .sf-menu-popover :where(a, button)[data-variant="danger"]:hover {
+    background: var(--sf-colour-danger-soft);
+  }
+
   .sf-tooltip {
     border-radius: var(--sf-radius-md);
     box-shadow: var(--sf-shadow-md);
@@ -1345,6 +1497,16 @@
     top: var(--sf-space-s);
   }
 
+  .sf-toast-stack {
+    display: grid;
+    gap: var(--sf-space-xs);
+    inline-size: min(100% - (var(--sf-gutter) * 2), var(--sf-toast-width, 24rem));
+    inset-block-start: var(--sf-space-s);
+    inset-inline-end: var(--sf-space-s);
+    position: fixed;
+    z-index: var(--sf-z-toast);
+  }
+
   .sf-banner {
     block-size: auto;
     border-radius: var(--sf-radius-lg);
@@ -1457,15 +1619,23 @@
   }
 
   .sf-tab {
+    align-items: center;
     border-block-end: 0.125rem solid transparent;
+    border-radius: var(--sf-radius-full);
     color: var(--sf-colour-muted);
     display: inline-flex;
+    gap: var(--sf-space-2xs);
     font-weight: 800;
     padding-block: var(--sf-space-xs);
     padding-inline: var(--sf-space-s);
     text-decoration: none;
   }
 
+  .sf-tab[data-variant="pill"] {
+    border: 1px solid transparent;
+    padding-block: var(--sf-space-2xs);
+  }
+
   .sf-tab:hover,
   .sf-tab[aria-selected="true"],
   .sf-tab[data-state="active"] {
@@ -1473,6 +1643,24 @@
     color: var(--sf-colour-foreground);
   }
 
+  .sf-tab[data-variant="pill"]:hover,
+  .sf-tab[data-variant="pill"][aria-selected="true"],
+  .sf-tab[data-variant="pill"][data-state="active"] {
+    background: var(--sf-colour-primary-soft);
+    border-color: var(--sf-colour-primary-soft-border);
+    color: var(--sf-colour-primary);
+  }
+
+  .sf-tab__count {
+    background: var(--sf-colour-surface-alt);
+    border: 1px solid var(--sf-colour-border);
+    border-radius: var(--sf-radius-full);
+    color: var(--sf-colour-muted);
+    font-size: var(--sf-step--2);
+    line-height: 1;
+    padding: .25em .55em;
+  }
+
   .sf-tab-panel {
     background: var(--sf-colour-surface);
     border: 1px solid var(--sf-colour-border);

package/docs/api-contract.md

@@ -13,9 +13,9 @@ These are intended for application code and examples.
 | Imports | `@syncedco/flow/styles.css`, `tokens.css`, `reset.css`, `base.css`, `defaults.css`, `layout.css`, `components.css`, `utilities.css` |
 | Tokens | Unlayered `--sf-*` custom properties emitted by `tokens.css` |
 | Theme config | `theme.fonts`, `theme.colours`, `theme.darkColours`, `theme.radii`, `theme.layout`, `theme.components` |
-| Layout classes | `sf-container`, `sf-section`, `sf-stack`, `sf-flow`, `sf-cluster`, `sf-repel`, `sf-toolbar`, `sf-app-shell`, `sf-app-sidebar`, `sf-app-main`, `sf-auto-grid`, `sf-switcher`, `sf-sidebar`, `sf-split`, `sf-frame`, `sf-cover`, `sf-metric-grid`, `sf-pipeline` |
-| Components | `sf-button`, `sf-icon`, `sf-icon-button`, `sf-avatar`, `sf-chart`, `sf-meter`, `sf-progress`, `sf-skeleton`, `sf-filter-bar`, `sf-data-table`, `sf-status`, `sf-data-list`, `sf-empty-state`, `sf-settings-section`, `sf-detail-panel`, `sf-card`, `sf-surface`, `sf-hero`, `sf-nav`, `sf-form`, `sf-field`, `sf-input`, `sf-select`, `sf-textarea`, `sf-check`, `sf-alert`, `sf-badge`, `sf-section-header`, `sf-kicker` |
-| Native components | `sf-dialog`, `sf-popover`, `sf-tooltip`, `sf-drawer`, `sf-drawer--stack`, `sf-disclosure`, `sf-accordion`, `sf-tabs`, `sf-menu`, `sf-breadcrumb`, `sf-pagination` |
+| Layout classes | `sf-container`, `sf-section`, `sf-stack`, `sf-flow`, `sf-cluster`, `sf-repel`, `sf-toolbar`, `sf-app-shell`, `sf-app-header`, `sf-app-sidebar`, `sf-app-backdrop`, `sf-app-main`, `sf-auto-grid`, `sf-switcher`, `sf-sidebar`, `sf-split`, `sf-frame`, `sf-cover`, `sf-metric-grid`, `sf-pipeline` |
+| Components | `sf-button`, `sf-icon`, `sf-icon-button`, `sf-avatar`, `sf-chart`, `sf-meter`, `sf-progress`, `sf-skeleton`, `sf-filter-bar`, `sf-search`, `sf-data-table`, `sf-table-sort`, `sf-status`, `sf-data-list`, `sf-empty-state`, `sf-settings-section`, `sf-detail-panel`, `sf-card`, `sf-surface`, `sf-hero`, `sf-nav`, `sf-form`, `sf-field`, `sf-input`, `sf-select`, `sf-textarea`, `sf-check`, `sf-alert`, `sf-badge`, `sf-section-header`, `sf-kicker` |
+| Native components | `sf-dialog`, `sf-popover`, `sf-tooltip`, `sf-drawer`, `sf-drawer--stack`, `sf-disclosure`, `sf-accordion`, `sf-tabs`, `sf-tab__count`, `sf-menu`, `sf-breadcrumb`, `sf-pagination`, `sf-toast-stack` |
 | Website patterns | `sf-logo-cloud`, `sf-feature`, `sf-stats`, `sf-testimonial`, `sf-pricing-grid`, `sf-price-card`, `sf-faq`, `sf-cta`, `sf-footer` |
 | Utilities | `sf-prose`, `sf-link`, `sf-link-subtle`, `sf-link-plain`, `sf-list-*`, `sf-push-*`, `sf-focus-ring`, `sf-touch-target`, `sf-skip-link`, `sr-only`, `not-sr-only` |
 | CLI | `synced-flow init`, `agents install`, `agents status`, `skill`, `add defaults`, `build`, `watch`, `lint`, `doctor`, `tokens`, `catalog`, `suggest`, `pattern`, `recipe`, `theme init`, `theme validate` |

package/docs/audit-2026-06.md

@@ -0,0 +1,113 @@
+# Synced Flow Audit — June 2026 (v0.3.0)
+
+Independent audit of `@syncedco/flow` at v0.3.0 (`a8a1f68`), run across three
+passes: product coherence (claims vs shipped), CSS quality, and tooling/release
+engineering. Findings are grounded in the source and in real consumer feedback
+from the Synced CRM (`synced-crm`, the first production app consumer).
+
+## Verdict
+
+Flow delivers its **original model (websites/agency) almost completely** and
+the **engineering discipline behind it impressively**. It falls short in three
+places: **app-tier depth**, **advanced theming scope**, and a few product
+positioning/docs gaps. It is a real, well-built system, and the positioning now
+fits better as AI-friendly / agent-ready.
+
+| Dimension | Rating | Summary |
+|---|---|---|
+| Fluid foundation (tokens, scales, layout) | ✅ Excellent | Genuine Utopia-style fluidity; modern CSS (layers, oklch, logical props, container queries); clean layer hygiene |
+| Website/agency coverage | ✅ ~90% | Everything claimed ships; agency-ready without custom CSS |
+| Tooling & release engineering | ✅ Excellent | 14 tested CLI commands, guardrails (size budgets, zero-dep, px policy), 40/40 tests, automated tag-driven publishing |
+| App/SaaS tier (0.2–0.3) | ⚠️ ~60% | Real scaffolding (proven by the CRM) but thin; consumers carry 20–40% custom CSS |
+| Dark mode | ✅ Patched after audit | `.sf-theme-dark` now overrides primary/status/soft/ring/glow tokens rather than inheriting light-tuned values |
+| Theming config | ✅ Documented boundary | Config handles global light/dark token themes; advanced per-surface/multi-variant theming belongs in project CSS token scopes |
+| AI positioning | ✅ Reframed | Positioning now uses AI-friendly / agent-ready language for the shipped CLI, skill, and agent guidance |
+| Docs | ⚠️ Improving | Website docs thorough; CHANGELOG and theming-scope docs added; app-tier docs can still mature |
+
+## Confirmed bugs (found by the CRM, verified in source)
+
+1. **Drawer can't scroll** — fixed after audit by adding `block-size: 100dvh`
+   to `.sf-app-shell[data-mobile="drawer"] .sf-app-sidebar`, giving the
+   existing `overflow: auto` a real viewport-height scroll container.
+2. **`.sf-tab` not vertically centred** — fixed after audit with
+   `align-items: center`.
+3. **`.sf-filter-bar` `align-items: end`** — fixed after audit with
+   `align-items: var(--sf-filter-bar-align, center)`, preserving a project
+   escape hatch without adding a new component variant.
+4. **`.sf-status` dot is mandatory** — fixed after audit with
+   `data-dot="false"` and `sf-status--label` opt-outs.
+
+## Higher-severity findings the CRM did NOT hit
+
+These mattered because no consumer had exercised them yet. They are now patched
+or documented, but should still be validated in the next real consumer.
+
+5. **Dark mode token coverage is critically incomplete** — fixed after audit
+   for the shipped base theme by adding dark-mode primary, state, soft, ring,
+   and glow token overrides.
+6. **Z-index scale is compressed and undocumented** — fixed after audit with
+   public `--sf-z-*` tokens wired into header, backdrop, drawer, overlay, toast,
+   sticky, and skip-link layers.
+7. **Missing `prefers-reduced-motion` guards** — fixed after audit for
+   `.sf-button:hover`, `.sf-card--interactive:hover`, and the marquee track.
+
+## Theming model limitation (real, undocumented)
+
+Config supports global light + `darkColours` + per-preset overrides. It does
+not try to express per-surface / multi-variant theming (e.g. `[data-theme]` ×
+`[data-surface]` matrices, per-tenant white-label, density-by-context). That is
+a legitimate design choice for Synced Flow's scope, and `config-reference.md`
+now documents the hand-written token-scope pattern for advanced cases.
+
+## AI-Friendly Positioning
+
+What ships is real and good: `catalog --json`, `suggest`, `pattern`, `recipe`,
+`lint`, `doctor`, a packaged skill, and `agents install` for 8 targets. The
+project now describes this as **AI-friendly** and agent-readable tooling rather
+than implying runtime AI integration.
+
+## App-tier coverage gaps (from real CRM adoption)
+
+Shipped and adopted: app-shell, data-table, empty-state, filter-bar, status
+chips, tabs, toast skin, form field shells. Still missing for production app
+work (CRM kept custom or deferred): combobox/searchable select, pagination
+depth (page size, jump-to-page), modal-with-form as a primitive (not just a
+pattern), bulk-actions toolbar, multi-step/wizard, skeleton loading compounds,
+sticky-header + horizontal-scroll tables. Kanban/timesheet/invoice-doc are
+deliberately consumer-specific and out of scope.
+
+## Strengths (keep doing)
+
+- Real fluidity; modern CSS; excellent cascade-layer hygiene.
+- Tooling/release engineering is the strongest area: guardrails enforce
+  zero-dependency, per-layer gzip size budgets, layer order, and a raw-px
+  policy; 40/40 tests pass; tag-driven OIDC publishing; complete exports map.
+- CLI catalog currently in sync with shipped CSS (verified) — though by hand.
+- AI agent guidance (skill + `agents install`) is current with 0.3.0 primitives.
+
+## Recommended roadmap
+
+**0.3.1 — bug patch (small, soon):**
+1. Drawer viewport scroll container. ✅
+2. `.sf-tab` `align-items: center`. ✅
+3. `.sf-filter-bar` tokenized alignment with centered default. ✅
+4. `.sf-status` dot opt-out. ✅
+5. `prefers-reduced-motion` guards on hover transforms + marquee. ✅
+
+**0.4.0 — structural gaps:**
+6. Continue dark-mode validation with a real consumer using Flow's built-in
+   theme selectors.
+7. Begin app-tier depth: combobox, pagination, modal-with-form, bulk-actions —
+   prioritised by what the CRM had to keep custom.
+
+**Docs / positioning / CI (cheap, high-trust):**
+8. CI: smoke-build the examples; add a test asserting the CLI catalog matches
+    the shipped CSS (in sync today only by hand); consider a CSS parse/lint and
+    a small visual-regression pass.
+
+## Meta-observation
+
+The four bugs the CRM surfaced are exactly the class only a real consumer finds
+— the proving-ground loop is working as intended. The most useful next
+validation step is getting a second consumer, or the CRM itself, onto Flow's
+built-in dark mode and app primitives before 1.0.

package/docs/config-reference.md

@@ -79,3 +79,30 @@ theme: {
   },
 }
 ```
+
+## Theme Scope
+
+The config theme model is intentionally global. Use `theme.colours` for the
+default token set and `theme.darkColours` for `.sf-theme-dark` /
+`[data-sf-theme="dark"]` overrides. This covers the common site or app case:
+one brand token set, with an optional dark-mode token set.
+
+Synced Flow does not try to encode every theme matrix in config. If a project
+needs per-tenant branding, `[data-surface]` variants, density-by-context, or
+other multi-axis theme rules, keep the reusable defaults in config and write
+the extra token scopes in project CSS:
+
+```css
+[data-tenant="acme"] {
+  --sf-colour-primary: oklch(62% 0.19 252);
+  --sf-colour-primary-hover: oklch(56% 0.19 252);
+}
+
+[data-surface="inset"] {
+  --sf-colour-surface: var(--sf-colour-surface-inset);
+  --sf-card-padding: var(--sf-space-s);
+}
+```
+
+Use this pattern for deliberate product theming. Avoid scattering one-off
+colour values through page components when a value can live in a token scope.

package/docs/patterns.md

@@ -18,6 +18,13 @@ pnpm exec synced-flow pattern scroll-viewport-sections --json
 | `scroll-viewport-with-spy` | Scroll snap panels with optional IntersectionObserver active-state notes. |
 | `native-dialog-react` | Native `<dialog>` markup plus React/Next fallback shape. |
 | `popover-drawer-layout` | Popover-backed drawer or filter panel with `sf-drawer--stack`. |
+| `app-shell-layout` | Fixed header, sidebar, collapsed state, and mobile drawer app shell. |
+| `row-action-menu` | Native popover row actions with destructive menu item styling. |
+| `tabs-with-counts` | Pill tabs with compact count chips. |
+| `data-table-actions` | Sortable header controls, clickable rows, and responsive card fallback. |
+| `search-field` | Labelled native search input with icon shell and compact density. |
+| `modal-form` | Native dialog layout for form body and footer actions. |
+| `toast-stack` | Fixed app notification stack layout. |
 | `filter-toolbar` | Search, filters, and actions above app lists and tables. |
 | `date-filter-form` | Native date/time inputs inside filter forms. |
 | `active-filter-tags` | Visible selected filter tags with remove and clear actions. |

package/docs/system-primitives.md

@@ -14,7 +14,10 @@ Use the `--sf-*` variables as the stable CSS foundation.
 | Space | `--sf-space-s`, `--sf-space-m-l`, `--sf-space-xl-2xl` | Fluid padding, margin, and gaps. |
 | Radius | `--sf-radius-control`, `--sf-radius-panel`, `--sf-radius-full` | Controls, panels, pills. |
 | Colour | `--sf-colour-background`, `--sf-colour-surface`, `--sf-colour-primary` | Semantic UI colour roles. |
+| App colour | `--sf-colour-surface-hover`, `--sf-colour-surface-raised-2`, `--sf-colour-border-subtle`, `--sf-colour-backdrop` | App surfaces, hover states, subtle dividers, and overlays. |
+| Categorical colour | `--sf-colour-categorical-1` ... `--sf-colour-categorical-6` | Charts, stages, labels, and recurring data accents. |
 | State | `--sf-colour-success`, `--sf-colour-warning`, `--sf-colour-danger`, `--sf-colour-info` | Feedback and notices. |
+| Z-index | `--sf-z-header`, `--sf-z-backdrop`, `--sf-z-drawer`, `--sf-z-overlay`, `--sf-z-toast` | Shared stacking slots for app chrome, drawers, popovers, and feedback. |
 | Motion | `--sf-duration-fast`, `--sf-duration-normal`, `--sf-ease-standard` | Consistent transitions. |
 | Component | `--sf-button-*`, `--sf-card-*`, `--sf-input-*`, `--sf-alert-*` | Reusable component defaults. |
 | Accessibility | `:focus-visible`, `:target`, `[aria-invalid]`, `[aria-current]`, `[aria-expanded]`, `[aria-selected]`, `[aria-busy]`, `[aria-disabled]` | Visible native and ARIA states. |
@@ -36,7 +39,7 @@ These classes are the first choice for page structure.
 | `sf-cluster` | Wrapping inline groups such as actions or tags. |
 | `sf-repel` | Space-between layout that wraps safely. |
 | `sf-toolbar` | Dense app/page toolbar that wraps actions safely. |
-| `sf-app-shell`, `sf-app-sidebar`, `sf-app-sidebar__brand`, `sf-app-main` | Product app shell with persistent sidebar and main workspace. |
+| `sf-app-shell`, `sf-app-header`, `sf-app-sidebar`, `sf-app-sidebar__brand`, `sf-app-backdrop`, `sf-app-main` | Product app shell with optional fixed header, collapsed sidebar, mobile drawer, and main workspace. |
 | `sf-split` | Responsive two-column layout. |
 | `sf-split--reverse` | Reverses split layout visual order. |
 | `sf-auto-grid`, `sf-panel-grid`, `sf-metric-grid`, `sf-pipeline` | Responsive card, metric, and operational grids. |
@@ -62,16 +65,16 @@ These cover the common UI elements needed for a simple site.
 | `sf-nav`, `sf-nav__list`, `sf-nav__link` | Navigation basics. |
 | `sf-nav--mobile`, `sf-menu`, `sf-breadcrumb`, `sf-pagination` | Mobile, menu, breadcrumb, and paginated navigation. |
 | `sf-dialog`, `sf-dialog__header`, `sf-dialog__body`, `sf-dialog__footer` | Native `<dialog>` styling. |
-| `sf-popover`, `sf-tooltip`, `sf-tooltip-trigger`, `sf-menu-popover`, `sf-toast`, `sf-banner`, `sf-drawer` | Popover-backed native overlays. |
+| `sf-popover`, `sf-tooltip`, `sf-tooltip-trigger`, `sf-menu-popover`, `sf-toast`, `sf-toast-stack`, `sf-banner`, `sf-drawer` | Popover-backed native overlays and app feedback stacks. |
 | `sf-disclosure`, `sf-accordion` | Native `details`/`summary` disclosure patterns. |
-| `sf-tabs`, `sf-tab-list`, `sf-tab`, `sf-tab-panel` | HTML/CSS-first tab styling. |
+| `sf-tabs`, `sf-tab-list`, `sf-tab`, `sf-tab__count`, `sf-tab-panel` | HTML/CSS-first tab styling, including counted pill tabs. |
 | `sf-form`, `sf-fieldset`, `sf-field`, `sf-label`, `sf-help`, `sf-error` | Form structure and messaging. |
-| `sf-input`, `sf-select`, `sf-textarea`, `sf-check` | Form controls. |
+| `sf-input`, `sf-select`, `sf-textarea`, `sf-search`, `sf-check` | Form controls, including search input shell. |
 | `sf-alert`, `sf-alert--info`, `sf-alert--success`, `sf-alert--warning`, `sf-alert--danger`, `sf-alert__title` | Notices and feedback. |
 | `sf-section-header`, `sf-kicker`, `sf-badge`, `sf-avatar` | Common marketing/content and account patterns. |
 | `sf-chart`, `sf-chart__plot`, `sf-chart__svg`, `sf-chart__legend`, `sf-meter-list`, `sf-meter` | Lightweight chart shells for app-owned SVG charts and native meter bars. |
 | `sf-progress`, `sf-skeleton` | Native progress bars and CSS-only loading placeholders for async app states. |
-| `sf-filter-bar`, `sf-data-table`, `sf-status`, `sf-data-list`, `sf-empty-state`, `sf-settings-section`, `sf-detail-panel` | Lean application primitives for filters, operational data, status, empty states, and settings/detail screens. |
+| `sf-filter-bar`, `sf-data-table`, `sf-table-sort`, `sf-status`, `sf-data-list`, `sf-empty-state`, `sf-settings-section`, `sf-detail-panel` | Lean application primitives for filters, operational data, status, empty states, and settings/detail screens. |
 
 ## Utility Classes
 

package/docs/tokens.md

@@ -75,6 +75,7 @@ The generated core includes enough semantic variables for common website UI:
 
 - surfaces: `--sf-colour-background`, `--sf-colour-surface`,
   `--sf-colour-surface-alt`, `--sf-colour-surface-raised`,
+  `--sf-colour-surface-raised-2`, `--sf-colour-surface-hover`,
   `--sf-colour-surface-inset`
 - text and links: `--sf-colour-foreground`, `--sf-colour-muted`,
   `--sf-colour-subtle`, `--sf-colour-link`, `--sf-colour-link-hover`
@@ -82,8 +83,13 @@ The generated core includes enough semantic variables for common website UI:
   `--sf-colour-primary-foreground`, `--sf-colour-primary-soft`
 - state feedback: `--sf-colour-success`, `--sf-colour-warning`,
   `--sf-colour-danger`, `--sf-colour-info`, plus matching soft variants
-- structure: `--sf-colour-border`, `--sf-colour-border-strong`,
+- structure: `--sf-colour-border-subtle`, `--sf-colour-border`,
+  `--sf-colour-border-strong`, `--sf-colour-backdrop`,
   `--sf-radius-control`, `--sf-radius-panel`, `--sf-shadow-*`
+- stacking: `--sf-z-sticky`, `--sf-z-header`, `--sf-z-backdrop`,
+  `--sf-z-drawer`, `--sf-z-overlay`, `--sf-z-toast`, `--sf-z-skip-link`
+- data accents: `--sf-colour-categorical-1` through
+  `--sf-colour-categorical-6`
 
 For class-level usage, see [System primitives](system-primitives.md).
 

package/docs/why-synced-flow.md

@@ -22,7 +22,7 @@ Synced Flow is designed to reduce the number of styling decisions made from scra
 
 Synced Flow is not trying to be a Tailwind clone, a Bootstrap replacement, or a React component library.
 
-It is an AI-native fluid CSS design system for brand-consistent websites and agency builds.
+It is an AI-friendly fluid CSS design system for brand-consistent websites and agency builds.
 
 Use it when you want:
 

package/layout.css

@@ -95,11 +95,47 @@
   }
 
   .sf-app-shell {
+    --sf-app-header-height: 4rem;
+    --sf-app-sidebar-collapsed-width: 4.75rem;
     background: var(--sf-colour-background);
     color: var(--sf-colour-foreground);
     display: grid;
     grid-template-columns: minmax(14rem, var(--sf-app-sidebar-width, 16rem)) minmax(0, 1fr);
     min-block-size: 100dvh;
+    position: relative;
+    transition: grid-template-columns var(--sf-duration-normal) var(--sf-ease-standard);
+  }
+
+  .sf-app-header {
+    align-items: center;
+    background: var(--sf-colour-surface);
+    border-block-end: 1px solid var(--sf-colour-border);
+    display: flex;
+    gap: var(--sf-space-s);
+    grid-column: 1 / -1;
+    justify-content: space-between;
+    min-block-size: var(--sf-app-header-height);
+    padding-inline: var(--sf-space-s-m);
+    z-index: var(--sf-z-header);
+  }
+
+  .sf-app-shell[data-layout~="fixed-header"] {
+    grid-template-rows: var(--sf-app-header-height) minmax(0, 1fr);
+  }
+
+  .sf-app-shell[data-layout~="fixed-header"] .sf-app-header {
+    inset-block-start: 0;
+    position: sticky;
+  }
+
+  .sf-app-shell[data-layout~="fixed-header"] .sf-app-sidebar {
+    inset-block-start: var(--sf-app-header-height);
+    max-block-size: calc(100dvh - var(--sf-app-header-height));
+    min-block-size: calc(100dvh - var(--sf-app-header-height));
+  }
+
+  .sf-app-shell[data-collapsed="true"] {
+    grid-template-columns: var(--sf-app-sidebar-collapsed-width) minmax(0, 1fr);
   }
 
   .sf-app-sidebar {
@@ -115,6 +151,7 @@
     padding: var(--sf-space-s);
     position: sticky;
     inset-block-start: 0;
+    transition: transform var(--sf-duration-normal) var(--sf-ease-standard), inline-size var(--sf-duration-normal) var(--sf-ease-standard);
   }
 
   .sf-app-sidebar__brand {
@@ -134,6 +171,59 @@
     padding: var(--sf-app-main-padding, var(--sf-space-m-l));
   }
 
+  .sf-app-shell[data-collapsed="true"] .sf-app-sidebar {
+    overflow-x: hidden;
+  }
+
+  .sf-app-shell[data-collapsed="true"] .sf-app-sidebar__brand,
+  .sf-app-shell[data-collapsed="true"] .sf-app-sidebar .sf-nav__link {
+    justify-content: center;
+  }
+
+  .sf-app-shell[data-collapsed="true"] [data-hide-collapsed="true"] {
+    display: none;
+  }
+
+  .sf-app-backdrop {
+    display: none;
+  }
+
+  @media (max-width: 48rem) {
+    .sf-app-shell[data-mobile="drawer"] {
+      display: block;
+    }
+
+    .sf-app-shell[data-mobile="drawer"] .sf-app-header {
+      position: sticky;
+      inset-block-start: 0;
+    }
+
+    .sf-app-shell[data-mobile="drawer"] .sf-app-sidebar {
+      block-size: 100dvh;
+      box-shadow: var(--sf-shadow-xl);
+      inline-size: min(18rem, calc(100vw - var(--sf-space-l)));
+      inset-block: 0;
+      inset-inline-start: 0;
+      max-block-size: none;
+      min-block-size: 100dvh;
+      position: fixed;
+      transform: translateX(-100%);
+      z-index: var(--sf-z-drawer);
+    }
+
+    .sf-app-shell[data-mobile="drawer"][data-sidebar-open="true"] .sf-app-sidebar {
+      transform: translateX(0);
+    }
+
+    .sf-app-shell[data-mobile="drawer"][data-sidebar-open="true"] .sf-app-backdrop {
+      background: var(--sf-colour-backdrop);
+      display: block;
+      inset: 0;
+      position: fixed;
+      z-index: var(--sf-z-backdrop);
+    }
+  }
+
   .sf-grid {
     display: grid;
     gap: var(--sf-grid-gap, var(--sf-gutter));
@@ -274,7 +364,7 @@
   .sf-sticky-top {
     position: sticky;
     inset-block-start: var(--sf-sticky-offset, 0);
-    z-index: var(--sf-sticky-z, 20);
+    z-index: var(--sf-sticky-z, var(--sf-z-sticky));
   }
 
   .sf-media-object {