@syncedco/flow 0.3.1 → 0.4.1

package/dist/index.js

@@ -42,10 +42,79 @@ export const fluidSystem = {
     },
     components: {
         button: 'sf-button',
+        buttonGroup: 'sf-button-group',
+        icon: 'sf-icon',
+        iconButton: 'sf-icon-button',
         card: 'sf-card',
+        surface: 'sf-surface',
+        hero: 'sf-hero',
+        logoCloud: 'sf-logo-cloud',
+        feature: 'sf-feature',
+        stats: 'sf-stats',
+        testimonial: 'sf-testimonial',
+        pricingGrid: 'sf-pricing-grid',
+        faq: 'sf-faq',
+        callToAction: 'sf-cta',
+        footer: 'sf-footer',
         badge: 'sf-badge',
+        avatar: 'sf-avatar',
+        alert: 'sf-alert',
+        status: 'sf-status',
+        sectionHeader: 'sf-section-header',
+        kicker: 'sf-kicker',
+        nav: 'sf-nav',
+        form: 'sf-form',
+        fieldset: 'sf-fieldset',
         field: 'sf-field',
+        label: 'sf-label',
+        help: 'sf-help',
+        error: 'sf-error',
         input: 'sf-input',
+        inputGroup: 'sf-input-group',
+        select: 'sf-select',
+        textarea: 'sf-textarea',
+        check: 'sf-check',
+        switch: 'sf-switch',
+        fileInput: 'sf-file-input',
+        range: 'sf-range',
+        segmentedControl: 'sf-segmented-control',
+        spinner: 'sf-spinner',
+        search: 'sf-search',
+        combobox: 'sf-combobox',
+        filterBar: 'sf-filter-bar',
+        bulkActions: 'sf-bulk-actions',
+        dataTable: 'sf-data-table',
+        tableSort: 'sf-table-sort',
+        dataList: 'sf-data-list',
+        emptyState: 'sf-empty-state',
+        settingsSection: 'sf-settings-section',
+        detailPanel: 'sf-detail-panel',
+        dialog: 'sf-dialog',
+        popover: 'sf-popover',
+        drawer: 'sf-drawer',
+        tooltip: 'sf-tooltip',
+        toast: 'sf-toast',
+        toastStack: 'sf-toast-stack',
+        banner: 'sf-banner',
+        disclosure: 'sf-disclosure',
+        accordion: 'sf-accordion',
+        tabs: 'sf-tabs',
+        tab: 'sf-tab',
+        menu: 'sf-menu',
+        breadcrumb: 'sf-breadcrumb',
+        pagination: 'sf-pagination',
+        stepper: 'sf-stepper',
+        wizardActions: 'sf-wizard-actions',
+        progress: 'sf-progress',
+        skeleton: 'sf-skeleton',
+        chart: 'sf-chart',
+        meter: 'sf-meter',
+        codeWindow: 'sf-code-window',
+        codeLines: 'sf-code-lines',
+        tokenStrip: 'sf-token-strip',
+        marquee: 'sf-marquee',
+        commandList: 'sf-command-list',
+        platformCard: 'sf-platform-card',
     },
     utilities: {
         visuallyHidden: 'sf-visually-hidden',

package/docs/accessibility-css.md

@@ -27,6 +27,8 @@ semantic HTML and ARIA states are visible, consistent, and easy to compose.
 | `[aria-disabled="true"]`, `:disabled` | Disabled affordance for buttons, links, cards, and form controls. |
 | `[aria-busy="true"]`, `[data-loading="true"]` | Busy/loading affordance for buttons and form controls. |
 | `.sf-field[data-invalid="true"]`, `[aria-invalid="true"]` | Invalid field styling. |
+| `.sf-switch input:checked`, `.sf-segmented-control input:checked` | Native checkbox/radio state shown without replacing the input semantics. |
+| `.sf-spinner` | Presentational loading indicator with a reduced-motion fallback; text status remains required. |
 | `.sf-required`, `.sf-label[aria-required="true"]`, `label:has(+ :required)` | Required-field marker styling. |
 | `@media (forced-colors: active)` | High contrast mode border, focus, and button fallbacks. |
 
@@ -111,13 +113,22 @@ messages that need immediate announcement.
 When an action is in progress, keep the accessible name visible and add state:
 
 ```html
-<button class="sf-button" type="button" aria-busy="true">
-  Saving
+<button class="sf-button" type="button" aria-busy="true" aria-disabled="true">
+  <span class="sf-spinner" aria-hidden="true"></span>
+  <span>Saving…</span>
 </button>
+<p class="sr-only" role="status" aria-live="polite">Saving changes</p>
 ```
 
 Synced Flow styles this as a busy state, but the consuming app should still
-manage focus, state changes, and completion messaging.
+manage focus, state changes, and completion messaging. `aria-disabled` keeps
+focus stable but does not block activation, so the app must guard its handler.
+Native `disabled` is also valid when removing the action from focus order is
+preferable.
+
+For a searchable select, the `sf-combobox` classes only style the shell. The
+app must implement the full combobox keyboard and ARIA contract. A static
+`role="combobox"` without synchronized state is not production-ready.
 
 ## Confidence Checklist
 

package/docs/ai-usage.md

@@ -53,7 +53,9 @@ before finalising the theme.
   `sf-split`, and `sf-sidebar` before writing custom layout CSS.
 - Use semantic colours: `bg-background`, `text-foreground`, `bg-primary`,
   `text-primary-foreground`, `border-border`, `bg-surface`.
-- Use `sf-button`, `sf-card`, `sf-badge`, `sf-field`, and `sf-input` for common UI.
+- Use `sf-button`, `sf-card`, `sf-badge`, `sf-field`, `sf-input`, `sf-switch`,
+  `sf-input-group`, `sf-file-input`, `sf-range`, and `sf-segmented-control` for
+  common UI.
 - Keep browser affordances unless the UI intentionally replaces them: body
   links stay underlined, content lists keep markers, and focus states remain
   visible.
@@ -78,6 +80,9 @@ before finalising the theme.
 - Choose `saas-landing` for public SaaS marketing pages. Choose
   `saas-dashboard` for authenticated app UI, admin panels, portals, CRMs,
   analytics dashboards, metrics, tables, account menus, and login state.
+- Choose `app-settings-workflow` for richer forms. Use the
+  `searchable-select`, `bulk-actions-toolbar`, `complete-pagination`, and
+  `multi-step-form` patterns for app-owned interactive behavior.
 - Treat auth recipe markup as UI only; sessions, providers, permissions, and
   sign-out logic belong to the consuming app.
 - Keep class names complete in source files. Do not build classes from fragments.
@@ -110,3 +115,19 @@ pnpm flow:doctor
 ```
 
 If `doctor` warns about stale CSS, run `pnpm flow:build`.
+
+## Machine-Readable Integration
+
+Synced Flow does not ship an MCP server. AI and external tool integrations
+should use the local CLI as the canonical discovery surface:
+
+```bash
+pnpm exec synced-flow tokens --json
+pnpm exec synced-flow catalog --json
+pnpm exec synced-flow suggest "searchable select settings" --json
+pnpm exec synced-flow pattern searchable-select --json
+pnpm exec synced-flow recipe app-settings-workflow --json
+```
+
+This keeps component names, app-owned behavior notes, accessibility guidance,
+and copy-ready markup in one versioned contract.

package/docs/api-contract.md

@@ -14,10 +14,12 @@ These are intended for application code and examples.
 | 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-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` |
+| Components | `sf-button`, `sf-spinner`, `sf-icon`, `sf-icon-button`, `sf-avatar`, `sf-chart`, `sf-meter`, `sf-progress`, `sf-skeleton`, `sf-filter-bar`, `sf-search`, `sf-input-group`, `sf-file-input`, `sf-range`, `sf-switch`, `sf-segmented-control`, `sf-combobox`, `sf-bulk-actions`, `sf-stepper`, `sf-wizard-actions`, `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-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` |
+| Technical presentation | `sf-code-window`, `sf-code-lines`, `sf-code-block`, `sf-code-token--*`, `sf-token-strip`, `sf-marquee`, `sf-command-list`, `sf-platform-card` |
 | 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` |
+| TypeScript runtime | `cx()` and the typed `fluidSystem.layout`, `fluidSystem.components`, and `fluidSystem.utilities` class shortcuts exported from `@syncedco/flow` |
 | CLI | `synced-flow init`, `agents install`, `agents status`, `skill`, `add defaults`, `build`, `watch`, `lint`, `doctor`, `tokens`, `catalog`, `suggest`, `pattern`, `recipe`, `theme init`, `theme validate` |
 
 ## AI Agent Contract
@@ -35,6 +37,12 @@ The project-level AI setup commands are public in 0.x:
 `catalog --json` includes `patterns[]` with copy-ready interaction metadata:
 classes, markup, JS requirement notes, accessibility notes, and gotchas.
 
+The package does not own an MCP server. Its supported machine-readable
+integration is the local CLI: `tokens --json`, `catalog --json`, `suggest
+--json`, and `pattern`/`recipe` JSON or markup output. External MCP tools may
+invoke those commands, but they should treat the CLI output as the package
+contract rather than maintaining a separate component inventory.
+
 ## Internal Or Compatibility Surface
 
 These can change more freely.

package/docs/audit-2026-06.md

@@ -68,13 +68,14 @@ 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.
+Shipped and adopted at audit time: app-shell, data-table, empty-state,
+filter-bar, status chips, tabs, toast skin, and form field shells. The later
+component-completeness batch adds the missing searchable-select presentation
+shell, page-size/jump pagination, bulk-actions toolbar, multi-step/wizard
+structure, switch, grouped/file/range inputs, segmented choice, and compact
+loading button. JavaScript state and keyboard behavior remain app-owned where
+the browser has no complete native primitive. Kanban/timesheet/invoice-doc
+remain deliberately consumer-specific and out of scope.
 
 ## Strengths (keep doing)
 
@@ -97,13 +98,13 @@ deliberately consumer-specific and out of scope.
 **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.
+7. Add app-tier depth: combobox presentation, pagination, modal-with-form,
+   bulk-actions, and wizard structure. ✅ Implemented after the audit.
 
 **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.
+8. CI: the component-completeness batch adds a regression assertion that every
+   catalogued component selector ships in `styles.css`. Example smoke builds,
+   CSS parsing, and broader visual regression remain useful future additions.
 
 ## Meta-observation
 

package/docs/base-styling.md

@@ -111,3 +111,8 @@ The base layer uses cascade layers, logical properties, low-specificity
 `prefers-reduced-motion`. Utopia informs the fluid type, space, and grid
 tokens; Synced Flow owns the reset, accessibility helpers, and component
 defaults.
+
+The root element is kept at `font-size: 100%` rather than a fixed pixel value so
+browser and user font-size settings remain respected. Body copy starts from the
+fluid text token with `body { font-size: var(--sf-text-base); }`, where
+`--sf-text-base` maps to the existing body type scale.

package/docs/cli-reference.md

@@ -189,9 +189,11 @@ pnpm exec synced-flow pattern mobile-nav-drawer --framework next --markup
 pnpm exec synced-flow pattern scroll-viewport-sections --json
 ```
 
-Current interaction patterns include `mobile-nav-drawer`,
-`scroll-viewport-sections`, `scroll-viewport-with-spy`,
-`native-dialog-react`, and `popover-drawer-layout`. Pattern JSON includes
+Current interaction patterns include native navigation and overlays, app shell
+and data patterns, plus `switch-control`, `input-group`,
+`native-file-and-range`, `segmented-control`, `loading-button`,
+`searchable-select`, `bulk-actions-toolbar`, `complete-pagination`, and
+`multi-step-form`. Pattern JSON includes
 classes, framework markup, JS requirement notes, accessibility notes, and
 implementation gotchas.
 
@@ -210,9 +212,10 @@ pnpm exec synced-flow recipe coming-soon --json
 
 Current recipes include SaaS landing, scroll portfolio, agency homepage, blog
 index, article page, about timeline, team grid, contact page, 404, coming soon,
-and SaaS dashboard. Use `saas-landing` for public product marketing and
-`saas-dashboard` for authenticated app UI with account state, metrics, tables,
-and workspace navigation. Recipes are composed from public `sf-*` classes and
+SaaS dashboard, and application settings workflow. Use `saas-landing` for
+public product marketing, `saas-dashboard` for authenticated app UI, and
+`app-settings-workflow` for the richer form-control surface. Recipes are
+composed from public `sf-*` classes and
 are intended as copy-paste starting points rather than new utility APIs.
 
 Use `--framework html`, `--framework next`, `--framework react`, or

package/docs/config-reference.md

@@ -52,8 +52,8 @@ theme: {
   colours: {
     background: 'oklch(98.6% 0.006 80)',
     foreground: 'oklch(18% 0.026 250)',
-    primary: 'oklch(68% 0.18 44)',
-    primaryHover: 'oklch(60% 0.18 44)',
+    primary: 'oklch(50% 0.16 40)',
+    primaryHover: 'oklch(44% 0.14 40)',
     primaryForeground: 'oklch(100% 0 0)',
     border: 'oklch(18% 0.026 250 / 0.12)',
   },

package/docs/css-optimisation.md

@@ -1,6 +1,6 @@
 # CSS Optimisation Notes
 
-Current measurements from `pnpm build` on 2026-05-24.
+Current measurements from `pnpm build` on 2026-09-09.
 
 ## Developer Notes
 
@@ -33,14 +33,14 @@ Sizes are raw bytes and gzip bytes from `gzip -c`.
 
 | File | Raw | Gzip | Use |
 | --- | ---: | ---: | --- |
-| `tokens.css` | 9,505 B | 2,232 B | Design tokens only. |
-| `reset.css` | 713 B | 430 B | Reset layer only. |
-| `base.css` | 3,455 B | 1,152 B | Base element styles. |
-| `defaults.css` | 505 B | 296 B | Optional site/UI defaults for raw links, lists, and controls. |
-| `layout.css` | 7,510 B | 1,866 B | Layout primitives such as container, stack, grid, app shell, sidebar, scroll snap, sticky, media object, and split. |
-| `components.css` | 31,195 B | 5,001 B | Component primitives such as button, icon, avatar, chart, card, surface, nav, form, alert, native overlays, disclosure, tabs, website patterns, accessibility states, and input. |
-| `utilities.css` | 7,498 B | 1,886 B | Static type, prose, content, positioning, motion, accessibility, link, list, colour, border, and shadow helpers. |
-| `styles.css` | 59,051 B | 10,457 B | Full core stylesheet with tokens, reset, base, layout, components, and utilities. |
+| `tokens.css` | 11,953 B | 2,563 B | Design tokens only. |
+| `reset.css` | 731 B | 435 B | Reset layer only. |
+| `base.css` | 3,477 B | 1,163 B | Base element styles. |
+| `defaults.css` | 506 B | 302 B | Optional site/UI defaults for raw links, lists, and controls. |
+| `layout.css` | 12,195 B | 2,820 B | Layout primitives such as container, stack, grid, app shell, sidebar, scroll snap, sticky, media object, and split. |
+| `components.css` | 62,874 B | 9,319 B | Component primitives including complete forms, app data controls, native overlays, website patterns, loading states, and technical presentation. |
+| `utilities.css` | 7,550 B | 1,902 B | Static type, prose, content, positioning, motion, accessibility, link, list, colour, border, and shadow helpers. |
+| `styles.css` | 97,950 B | 15,776 B | Full core stylesheet with tokens, reset, base, layout, components, and utilities. |
 
 Example generated project CSS with tokens plus one scanned `text-primary`
 utility measured 7,031 B raw and 1,943 B gzip.
@@ -91,7 +91,7 @@ Safe claims:
 
 - Modern CSS-first: Synced Flow uses cascade layers, custom properties,
   `clamp()`, logical properties, OKLCH colour, and container-aware primitives.
-- Compact by default: the full core stylesheet is currently about 10.5 KB gzip.
+- Compact by default: the full core stylesheet is currently about 15.8 KB gzip.
 - Flexible loading: developers can import only the CSS layers their project
   uses.
 - Source-scanned utilities: project utility CSS is generated from actual class

package/docs/native-components.md

@@ -25,6 +25,127 @@ Synced Flow sets `color-scheme` for native controls, forms, dialogs, and
 popover-backed UI. Projects can toggle the attribute however they like; the
 package does not ship a JavaScript theme switcher.
 
+## Switches And Segmented Choices
+
+Use `sf-switch` only for a strict binary setting. The native checkbox owns the
+checked, keyboard, disabled, and form states. Keep the visible label unchanged
+when the value changes, and do not use `indeterminate` or `aria-checked="mixed"`
+for this pattern.
+
+```html
+<label class="sf-switch">
+  <input type="checkbox" role="switch" name="notifications" checked>
+  <span class="sf-switch__control" aria-hidden="true"></span>
+  <span class="sf-switch__label">Email notifications</span>
+</label>
+```
+
+Checkboxes do not have a native read-only state. Use `disabled` when a setting
+is unavailable. If a product needs a focusable but non-editable explanation,
+the app must implement and test that behavior rather than adding `readonly` to
+the checkbox.
+
+State mapping is deliberately small: omit `checked` for off, add `checked` for
+on, rely on native `:focus-visible` for keyboard focus, and add `disabled` to
+the input when unavailable. The visible label must stay the same in every
+state.
+
+Use the radio-backed segmented control for one choice from a small set. It is a
+form control, not a tab list and not a group of independent switches.
+
+```html
+<fieldset class="sf-fieldset">
+  <legend>Billing cycle</legend>
+  <div class="sf-segmented-control">
+    <label class="sf-segmented-control__option">
+      <input type="radio" name="cycle" value="monthly" checked>
+      <span class="sf-segmented-control__label">Monthly</span>
+    </label>
+    <label class="sf-segmented-control__option">
+      <input type="radio" name="cycle" value="annual">
+      <span class="sf-segmented-control__label">Annual</span>
+    </label>
+  </div>
+</fieldset>
+```
+
+Both controls include light/dark token behavior, visible keyboard focus,
+disabled styling, forced-colors fallbacks, and reduced-motion handling.
+
+## Input Groups, File Inputs, And Range Inputs
+
+`sf-input-group` composes one flexible input with leading/trailing content or
+an inline action. Prefixes that repeat visible label context should be hidden
+from assistive technology. Use `sf-search` for a normal search field.
+
+```html
+<label class="sf-field">
+  <span class="sf-label">Monthly budget</span>
+  <span class="sf-input-group">
+    <span class="sf-input-group__leading" aria-hidden="true">£</span>
+    <input class="sf-input" name="budget" inputmode="decimal">
+    <span class="sf-input-group__trailing" aria-hidden="true">GBP</span>
+  </span>
+</label>
+```
+
+Use `sf-file-input` and `sf-range` on their native input types. File previews,
+upload limits, live range output, and persistence belong to the app.
+
+```html
+<label class="sf-field">
+  <span class="sf-label">Supporting document</span>
+  <input class="sf-file-input" type="file" accept=".pdf,.doc,.docx">
+  <span class="sf-help">PDF or Word, up to 10 MB.</span>
+</label>
+
+<label class="sf-field">
+  <span class="sf-label">Team size: <output for="team-size">12</output></span>
+  <input class="sf-range" id="team-size" type="range" min="1" max="50" value="12">
+</label>
+```
+
+## Loading Buttons
+
+`sf-spinner` is a presentational indicator. A pending action must also expose a
+text status and use app state to prevent duplicate submission.
+
+```html
+<button class="sf-button" type="submit" aria-busy="true" aria-disabled="true">
+  <span class="sf-spinner" aria-hidden="true"></span>
+  <span>Saving…</span>
+</button>
+<p class="sr-only" role="status" aria-live="polite">Saving changes</p>
+```
+
+The spinner stops rotating under reduced motion while remaining visible.
+`aria-disabled` keeps an in-flight button in the focus order, but the app must
+prevent click and submit activation while it is set. Use native `disabled`
+instead when removing the action from the focus order is the better tradeoff.
+
+## App-Owned Interactive Shells
+
+Synced Flow includes presentation classes for searchable selects, selection
+toolbars, complete pagination, and multi-step forms. The copy-ready contracts
+live in the CLI:
+
+```bash
+pnpm exec synced-flow pattern searchable-select --markup
+pnpm exec synced-flow pattern bulk-actions-toolbar --markup
+pnpm exec synced-flow pattern complete-pagination --markup
+pnpm exec synced-flow pattern multi-step-form --markup
+```
+
+The combobox shell does not implement filtering or keyboard behavior. The app
+must synchronize `aria-expanded`, `aria-controls`, `aria-activedescendant`, and
+`aria-selected`, and test the complete interaction with keyboard and assistive
+technology. Bulk selection, client-side pagination state, step validation,
+focus movement, persistence, and history are also app-owned.
+
+For a completed wizard step, include hidden text such as
+`<span class="sr-only">Completed: </span>` before the visible label. The tick
+or marker may remain `aria-hidden`; completion must still be available as text.
+
 ## Dialog
 
 Use `<dialog>` for modal UI. Style the dialog with `sf-dialog` and structure it

package/docs/patterns.md

@@ -31,6 +31,15 @@ pnpm exec synced-flow pattern scroll-viewport-sections --json
 | `data-table` | Native responsive table markup with status pills. |
 | `empty-state` | No-results and first-run states with clear next actions. |
 | `settings-section` | Settings/detail sections for account, team, billing, and security screens. |
+| `switch-control` | Native checkbox-backed binary setting switch. |
+| `input-group` | Prefix, suffix, unit, or inline-action input composition. |
+| `native-file-and-range` | Styled native file and bounded range inputs. |
+| `segmented-control` | Native radio-backed mutually exclusive choice. |
+| `loading-button` | Busy action with spinner and text/live-region guidance. |
+| `searchable-select` | Presentation shell and complete app-owned combobox contract. |
+| `bulk-actions-toolbar` | Selection count and list/table actions. |
+| `complete-pagination` | Result context, page links, page size, and direct page entry. |
+| `multi-step-form` | Step progress and form navigation structure with textual current and completed states. |
 
 Pattern JSON includes:
 
@@ -43,3 +52,12 @@ Pattern JSON includes:
 Use patterns before hand-rolling interaction markup. Use recipes for full-page
 composition and patterns for the tricky native interaction details inside those
 pages.
+
+Patterns with `requiresJs: true` are presentation and markup contracts. Synced
+Flow deliberately does not pretend that CSS supplies combobox keyboard
+behavior, async state, row selection, or wizard validation. The consuming app
+owns those behaviors and their browser/assistive-technology tests.
+
+Wizard completion cannot rely on the tick marker alone. Keep that decorative
+marker hidden from assistive technology and prefix completed labels with
+screen-reader text such as `Completed:`.

package/docs/quick-start.md

@@ -50,10 +50,11 @@ theme: {
     display: 'Fraunces, Georgia, serif',
   },
   colours: {
-    primary: 'oklch(68% 0.18 44)',
+    primary: 'oklch(50% 0.16 40)',
+    primaryHover: 'oklch(44% 0.14 40)',
     primaryForeground: 'oklch(100% 0 0)',
     accent: 'oklch(70% 0.12 205)',
-    ring: 'oklch(68% 0.18 44)',
+    ring: 'oklch(50% 0.16 40)',
   },
   components: {
     button: { radius: '0.5rem' },
@@ -153,7 +154,8 @@ export default defineConfig({
       display: 'Fraunces, Georgia, serif',
     },
     colours: {
-      primary: 'oklch(68% 0.18 44)',
+      primary: 'oklch(50% 0.16 40)',
+      primaryHover: 'oklch(44% 0.14 40)',
       secondary: 'oklch(62% 0.12 205)',
       tertiary: 'oklch(64% 0.14 185)',
       primaryForeground: 'oklch(100% 0 0)',
@@ -174,7 +176,7 @@ Use the CSS entry file for one-off local overrides.
 
 :root {
   --sf-font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
-  --sf-colour-primary: oklch(68% 0.18 44);
+  --sf-colour-primary: oklch(50% 0.16 40);
 }
 ```
 

package/docs/recipes.md

@@ -21,6 +21,7 @@ Available recipe ids:
 
 - `saas-landing`
 - `saas-dashboard`
+- `app-settings-workflow`
 - `portfolio-scroll`
 - `agency-home`
 - `blog-index`
@@ -31,6 +32,17 @@ Available recipe ids:
 - `not-found`
 - `coming-soon`
 
+`app-settings-workflow` composes the switch, grouped input, file and range
+inputs, segmented choice, combobox presentation shell, stepper, wizard actions,
+and loading-button structure. Generate the complete copy-ready markup with:
+
+```bash
+pnpm exec synced-flow recipe app-settings-workflow --markup
+```
+
+The consuming app still owns async state, upload handling, live range output,
+combobox keyboard behavior, step validation, persistence, and focus movement.
+
 ## Marketing Homepage
 
 ```html

package/docs/release-readiness.md

@@ -34,10 +34,19 @@ keep the CSS affordances in place.
   the system provides matching primitives.
 - Native disabled, required, invalid, `details[open]`, and `:target` states are
   styled.
+- Checkbox-backed switches remain strictly binary and radio-backed segmented
+  controls preserve native keyboard behavior.
+- Loading indicators have a text status; reduced motion leaves a visible
+  non-rotating indicator.
+- App-owned combobox, bulk-selection, pagination, and wizard examples clearly
+  name the JavaScript and focus behavior the consumer must implement.
 - Forced-colors fallbacks keep borders and focus outlines visible.
 - `prefers-reduced-motion` is respected by the base styles.
 - Examples use semantic landmarks, real buttons, real links, labels, help text,
   and native disclosure controls.
+- Every catalogue pattern and recipe has valid IDs and ID references and passes
+  automated WCAG A/AA checks in light and dark themes.
+- Native component behaviour passes in Chromium, Firefox, and WebKit.
 
 ## Documentation Checks
 
@@ -51,23 +60,39 @@ keep the CSS affordances in place.
 ## Commands
 
 ```bash
-pnpm build
+pnpm install --ignore-scripts
+pnpm build:types
+pnpm check:generated
 pnpm check
 pnpm test
+pnpm test:browser:all
+npm pack --dry-run
 node bin/synced-flow.mjs tokens --json
 node bin/synced-flow.mjs catalog --json
+node bin/synced-flow.mjs pattern switch-control --markup
+node bin/synced-flow.mjs pattern searchable-select --json
+node bin/synced-flow.mjs recipe app-settings-workflow --markup
 node bin/synced-flow.mjs doctor --cwd examples/plain-html
 ```
 
-If a browser-visible example changes, inspect it at mobile and desktop widths
-before calling the release ready.
+Run freshness checks before `pnpm build`, `pnpm install` without
+`--ignore-scripts`, or another lifecycle command can regenerate tracked CSS.
+The freshness gate covers the eight package layer/bundle files plus plain HTML,
+Vite, Next, Astro, and WordPress generated outputs. The unit suite semantically
+compiles all 35 patterns and 12 recipes for React and Next (94 generated TSX
+files), and exercises the generated React scroll-spy lifecycle. Browser tests
+use shipped CSS and generated markup to cover native keyboard/form behaviour,
+focus, reduced motion, forced colours, dialogs, responsive overflow, IDs, and
+light/dark Axe checks.
 
 ## npm Trusted Publishing
 
-Publishing is handled by `.github/workflows/npm-publish.yml` when a `v*` tag is
-pushed. The workflow checks that the tag matches `package.json`, installs with
-pnpm, runs tests, verifies package contents, and publishes with npm trusted
-publishing.
+Pull requests and `main` use `.github/workflows/ci.yml` to run the freshness,
+static, unit, package dry-run, and Chromium gates. Publishing is handled by
+`.github/workflows/npm-publish.yml` when a `v*` tag is pushed. Its release gate
+checks that the tag matches `package.json` and runs the same checks with
+Chromium, Firefox, and WebKit. The publish job can start only after that gate
+passes and is the only job granted npm trusted-publishing identity permission.
 
 Configure npm package trusted publishing for `@syncedco/flow` with:
 

package/docs/system-primitives.md

@@ -10,7 +10,7 @@ Use the `--sf-*` variables as the stable CSS foundation.
 | Layer | Examples | Use for |
 | --- | --- | --- |
 | Font | `--sf-font-sans`, `--sf-font-display`, `--sf-font-mono` | Site typography families. |
-| Type | `--sf-type-body`, `--sf-type-lead`, `--sf-type-h1`, `--sf-type-display` | Fluid text sizes. |
+| Type | `--sf-text-base`, `--sf-type-body`, `--sf-type-lead`, `--sf-type-h1`, `--sf-type-display` | Fluid text sizes. |
 | 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. |
@@ -63,18 +63,25 @@ These cover the common UI elements needed for a simple site.
 | `sf-surface`, `sf-surface--alt`, `sf-surface--raised` | Generic reusable panels. |
 | `sf-logo-cloud`, `sf-feature`, `sf-stats`, `sf-testimonial`, `sf-pricing-grid`, `sf-faq`, `sf-cta`, `sf-footer` | Common website patterns. |
 | `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-nav--mobile`, `sf-menu`, `sf-breadcrumb`, `sf-pagination`, `sf-pagination__summary`, `sf-pagination__controls`, `sf-pagination__pages`, `sf-pagination__jump` | Mobile, menu, breadcrumb, and complete 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-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__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-search`, `sf-check` | Form controls, including search input shell. |
+| `sf-input`, `sf-select`, `sf-textarea`, `sf-search`, `sf-input-group`, `sf-file-input`, `sf-range`, `sf-check` | Native form controls, search, grouped prefixes/suffixes/actions, file selection, and range input. |
+| `sf-switch`, `sf-switch__control`, `sf-switch__label` | Native checkbox-backed binary setting switch. |
+| `sf-segmented-control`, `sf-segmented-control__option`, `sf-segmented-control__label` | Native radio-backed single-choice control. |
+| `sf-spinner` | Compact loading indicator for buttons and small async surfaces. |
 | `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-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. |
+| `sf-combobox`, `sf-combobox__listbox`, `sf-combobox__option`, `sf-combobox__empty` | Presentation shell for an app-owned accessible searchable select. |
+| `sf-bulk-actions`, `sf-bulk-actions__count`, `sf-bulk-actions__controls` | Selection count and actions above a list or table. |
+| `sf-stepper`, `sf-stepper__step`, `sf-stepper__marker`, `sf-stepper__label`, `sf-wizard-actions` | Multi-step progress and form navigation structure. |
+| `sf-code-window`, `sf-code-lines`, `sf-code-block`, `sf-token-strip`, `sf-marquee`, `sf-command-list`, `sf-platform-card` | Public technical/product presentation primitives used by the catalogue and examples. |
 
 ## Utility Classes