@syncedco/flow 0.2.0 → 0.3.0

package/components.css

@@ -885,6 +885,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 +970,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;
@@ -1055,6 +1131,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 +1203,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 +1362,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 +1388,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,
@@ -1319,6 +1446,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 +1482,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: 50;
+  }
+
   .sf-banner {
     block-size: auto;
     border-radius: var(--sf-radius-lg);
@@ -1458,14 +1605,21 @@
 
   .sf-tab {
     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 +1627,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/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,6 +14,8 @@ 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. |
 | Motion | `--sf-duration-fast`, `--sf-duration-normal`, `--sf-ease-standard` | Consistent transitions. |
 | Component | `--sf-button-*`, `--sf-card-*`, `--sf-input-*`, `--sf-alert-*` | Reusable component defaults. |
@@ -36,7 +38,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 +64,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,11 @@ 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-*`
+- data accents: `--sf-colour-categorical-1` through
+  `--sf-colour-categorical-6`
 
 For class-level usage, see [System primitives](system-primitives.md).
 

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: 20;
+  }
+
+  .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,58 @@
     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 {
+      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: 30;
+    }
+
+    .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: 25;
+    }
+  }
+
   .sf-grid {
     display: grid;
     gap: var(--sf-grid-gap, var(--sf-gutter));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncedco/flow",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AI-native fluid CSS design system for brand-consistent websites and agency builds.",
   "type": "module",
   "packageManager": "pnpm@11.2.2",

package/skills/synced-flow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: synced-flow
-description: Use Synced Flow to set up and build modern fluid CSS systems with the CLI, tokens, presets, WordPress support, and source-scanned utility CSS.
+description: Use Synced Flow to set up and build modern fluid CSS systems with the CLI, tokens, presets, app UI primitives, WordPress support, and source-scanned utility CSS.
 ---
 
 # Synced Flow
@@ -87,12 +87,25 @@ intact. Leave out `utilities.css` unless static helpers such as `sf-text-*`,
 
 - Prefer primitives first: `sf-container`, `sf-section`, `sf-stack`,
   `sf-cluster`, `sf-repel`, `sf-auto-grid`, `sf-split`, `sf-sidebar`,
-  `sf-frame`, and `sf-flow`.
+  `sf-app-shell`, `sf-app-header`, `sf-app-sidebar`, `sf-app-main`,
+  `sf-app-backdrop`, `sf-frame`, and `sf-flow`.
 - Prefer component primitives for common UI: `sf-button`, `sf-card`,
-  `sf-badge`, `sf-field`, and `sf-input`.
-- Use `saas-landing` for public SaaS marketing pages. Use `saas-dashboard` for
-  authenticated app UI, admin panels, portals, CRMs, analytics dashboards,
-  metrics, tables, account menus, and login state.
+  `sf-badge`, `sf-status`, `sf-field`, `sf-input`, `sf-search`,
+  `sf-data-table`, `sf-table-sort`, `sf-tab__count`, and `sf-toast-stack`.
+- Use `saas-landing` for public SaaS marketing pages. Use `saas-dashboard` when
+  a full authenticated starter is useful, but prefer neutral app patterns for
+  reusable UI in admin panels, portals, CRMs, analytics dashboards, internal
+  tools, account areas, and product workspaces.
+- Use app patterns before writing project CSS:
+  `app-shell-layout`, `row-action-menu`, `tabs-with-counts`,
+  `data-table-actions`, `search-field`, `modal-form`, and `toast-stack`.
+- Use app shell states instead of bespoke layout CSS: `data-layout="fixed-header"`
+  for fixed app headers, `data-collapsed="true"` for collapsed sidebars, and
+  `data-mobile="drawer"` with `data-sidebar-open="true"` for mobile drawer
+  navigation.
+- Keep product-specific structures out of Synced Flow. Kanban boards, invoices,
+  proposal builders, scheduling workflows, and complex editable grids should stay
+  in the consuming app unless they become broadly reusable primitives.
 - Do not implement authentication logic in Synced Flow markup. Wire sessions,
   providers, permissions, and sign-out actions in the consuming app.
 - Prefer native component patterns for common interaction: `sf-dialog`,
@@ -112,6 +125,10 @@ intact. Leave out `utilities.css` unless static helpers such as `sf-text-*`,
   accessibility and explicit UI styling.
 - Put brand choices in `theme` config or theme presets rather than scattered
   one-off CSS.
+- Use semantic app tokens before local overrides: `surfaceRaised2`,
+  `surfaceHover`, `borderSubtle`, `backdrop`, and `categorical1` through
+  `categorical6`. Devs may still supply valid CSS colour formats such as hex,
+  RGB, HSL, or OKLCH in their own theme config.
 - Use modern CSS techniques already in the system: cascade layers, custom
   properties, logical properties, `clamp()`, OKLCH colour, container-aware
   layout, and `prefers-reduced-motion`.

package/src/tokens.mjs

@@ -75,9 +75,13 @@ export const semanticTokens = {
     surface: 'var(--sf-colour-neutral-0)',
     surfaceAlt: 'var(--sf-colour-neutral-100)',
     surfaceRaised: 'var(--sf-colour-neutral-0)',
+    surfaceRaised2: 'var(--sf-colour-neutral-50)',
+    surfaceHover: 'var(--sf-colour-neutral-100)',
     surfaceInset: 'var(--sf-colour-neutral-100)',
+    borderSubtle: 'oklch(18% 0.026 250 / 0.08)',
     border: 'oklch(18% 0.026 250 / 0.12)',
     borderStrong: 'oklch(18% 0.026 250 / 0.22)',
+    backdrop: 'oklch(0% 0 0 / 0.48)',
     primary: 'var(--sf-colour-orange-600)',
     primaryHover: 'var(--sf-colour-orange-700)',
     primaryForeground: 'var(--sf-colour-neutral-0)',
@@ -99,6 +103,12 @@ export const semanticTokens = {
     info: 'var(--sf-colour-cyan-600)',
     infoForeground: 'var(--sf-colour-neutral-0)',
     infoSoft: 'oklch(70% 0.12 205 / 0.14)',
+    categorical1: 'var(--sf-colour-cyan-600)',
+    categorical2: 'var(--sf-colour-green-600)',
+    categorical3: 'var(--sf-colour-amber-500)',
+    categorical4: 'var(--sf-colour-orange-600)',
+    categorical5: 'var(--sf-colour-red-600)',
+    categorical6: 'oklch(58% 0.15 292)',
     ring: 'var(--sf-colour-orange-600)',
   },
 }