@syncedco/flow 0.1.0

package/docs/recipes.md

@@ -0,0 +1,285 @@
+# Recipes
+
+These recipes are copy-ready starting points. They intentionally compose the
+public API from [System primitives](system-primitives.md) and avoid one-off page
+CSS.
+
+## CLI Recipe Catalog
+
+The CLI also ships page-level recipes for AI agents and template generators:
+
+```bash
+pnpm exec synced-flow recipe
+pnpm exec synced-flow recipe saas-landing --markup
+pnpm exec synced-flow recipe saas-dashboard --framework next --markup
+pnpm exec synced-flow recipe saas-landing --framework next --markup
+pnpm exec synced-flow recipe --section form --framework astro --markup
+pnpm exec synced-flow suggest "portfolio with full page scroll" --json
+```
+
+Available recipe ids:
+
+- `saas-landing`
+- `saas-dashboard`
+- `portfolio-scroll`
+- `agency-home`
+- `blog-index`
+- `article-page`
+- `about-timeline`
+- `team-grid`
+- `contact-page`
+- `not-found`
+- `coming-soon`
+
+## Marketing Homepage
+
+```html
+<a class="sf-skip-link" href="#main">Skip to main content</a>
+<header class="sf-container sf-repel" role="banner">
+  <a class="sf-link-plain sf-focus-ring" href="/">Acme Studio</a>
+  <nav class="sf-nav" aria-label="Primary">
+    <ul class="sf-nav__list">
+      <li><a class="sf-nav__link" href="#features" aria-current="page">Features</a></li>
+      <li><a class="sf-nav__link" href="#pricing">Pricing</a></li>
+      <li><a class="sf-nav__link" href="#contact">Contact</a></li>
+    </ul>
+  </nav>
+</header>
+
+<main id="main">
+  <section class="sf-hero">
+    <div class="sf-container sf-split">
+      <div class="sf-stack">
+        <p class="sf-kicker">Fluid by default</p>
+        <h1 class="sf-text-display">Launch a modern website without writing page CSS.</h1>
+        <p class="sf-text-lead sf-prose">Compose sections from tokens, layout primitives, patterns, and accessible form states.</p>
+        <div class="sf-cluster">
+          <a class="sf-button" href="#contact">Start a project</a>
+          <a class="sf-button sf-button--outline" href="#features">See features</a>
+        </div>
+      </div>
+      <aside class="sf-surface sf-stack" aria-label="Included primitives">
+        <h2 class="sf-text-h4">Included</h2>
+        <ul class="sf-list-disc">
+          <li>Fluid type and spacing</li>
+          <li>Layout and website patterns</li>
+          <li>Buttons, forms, cards, and states</li>
+        </ul>
+      </aside>
+    </div>
+  </section>
+
+  <section class="sf-section" id="features">
+    <div class="sf-container sf-stack">
+      <header class="sf-section-header">
+        <p class="sf-kicker">Features</p>
+        <h2 class="sf-text-h2">Common sections are already covered.</h2>
+      </header>
+      <div class="sf-auto-grid">
+        <article class="sf-feature">
+          <span class="sf-feature__icon" aria-hidden="true">1</span>
+          <h3 class="sf-feature__title">Tokens</h3>
+          <p class="sf-feature__text">Use semantic colour, type, space, radius, shadow, and component variables.</p>
+        </article>
+        <article class="sf-feature">
+          <span class="sf-feature__icon" aria-hidden="true">2</span>
+          <h3 class="sf-feature__title">Patterns</h3>
+          <p class="sf-feature__text">Build proof, pricing, FAQ, CTA, and footer sections from named classes.</p>
+        </article>
+        <article class="sf-feature">
+          <span class="sf-feature__icon" aria-hidden="true">3</span>
+          <h3 class="sf-feature__title">States</h3>
+          <p class="sf-feature__text">Focus, current, invalid, disabled, busy, and forced-colors states are visible.</p>
+        </article>
+      </div>
+    </div>
+  </section>
+</main>
+```
+
+## SaaS Product Page
+
+Use `saas-landing` for public marketing and product showcase pages.
+Use `saas-dashboard` for authenticated SaaS app screens, portals, CRMs, admin
+panels, and product workspaces.
+
+```html
+<main>
+  <section class="sf-section">
+    <div class="sf-container sf-stack">
+      <header class="sf-section-header">
+        <p class="sf-kicker">Product</p>
+        <h1 class="sf-text-h1">A calm operating layer for busy teams.</h1>
+        <p class="sf-text-lead sf-prose">Use the same primitives for landing pages, feature pages, and product-led flows.</p>
+      </header>
+      <div class="sf-logo-cloud" aria-label="Trusted by">
+        <span>Studio</span>
+        <span>Agency</span>
+        <span>Startup</span>
+        <span>Product</span>
+      </div>
+      <div class="sf-stats">
+        <article class="sf-stat">
+          <strong class="sf-stat__value">0</strong>
+          <span class="sf-stat__label">Runtime dependencies</span>
+        </article>
+        <article class="sf-stat">
+          <strong class="sf-stat__value">1</strong>
+          <span class="sf-stat__label">Core import</span>
+        </article>
+        <article class="sf-stat">
+          <strong class="sf-stat__value">10.5 KB</strong>
+          <span class="sf-stat__label">Full core gzip size</span>
+        </article>
+      </div>
+      <blockquote class="sf-testimonial">
+        <p class="sf-testimonial__quote">"Synced Flow gives us enough structure without locking the brand down."</p>
+        <footer class="sf-testimonial__meta">Example product team</footer>
+      </blockquote>
+    </div>
+  </section>
+</main>
+```
+
+## SaaS Dashboard And Auth State
+
+This recipe is CSS and markup only. Authentication, sessions, permissions, and
+providers belong to the consuming app.
+
+```bash
+pnpm exec synced-flow recipe saas-dashboard --markup
+pnpm exec synced-flow recipe saas-dashboard --framework next --markup
+pnpm exec synced-flow suggest "SaaS dashboard with login and metrics"
+```
+
+The recipe includes:
+
+- signed-out sign-in form
+- signed-in sidebar account area with initials, role, settings, and sign-out
+- Lucide-compatible inline SVG sidebar icons using `sf-icon`
+- Generic account initials using `sf-avatar`
+- Inline SVG and native meter analytics using `sf-chart` and `sf-meter`
+- traditional SaaS app shell with persistent desktop navigation and a visible stacked mobile navigation rail
+- KPI cards, theme-aware toolbar, filter/search form, customer table, and activity list
+
+It uses Synced Flow primitives such as `sf-app-shell`, `sf-app-sidebar`,
+`sf-app-main`, `sf-toolbar`, `sf-metric-grid`, `sf-panel-grid`, `sf-icon`,
+`sf-chart`, `sf-chart--wide`, `sf-meter`, `sf-card`, `sf-form`, and
+`sf-table-wrap`.
+
+## Documentation Page
+
+```html
+<main class="sf-section">
+  <div class="sf-container sf-sidebar">
+    <aside class="sf-sidebar__sidebar" aria-label="Documentation navigation">
+      <nav class="sf-nav">
+        <ul class="sf-nav__list">
+          <li><a class="sf-nav__link" href="#install" aria-current="page">Install</a></li>
+          <li><a class="sf-nav__link" href="#tokens">Tokens</a></li>
+          <li><a class="sf-nav__link" href="#components">Components</a></li>
+        </ul>
+      </nav>
+    </aside>
+    <article class="sf-sidebar__content sf-prose">
+      <h1 id="install">Install Synced Flow</h1>
+      <p>Import the full stylesheet for the smallest setup path, or use modular layers when a project needs tighter control.</p>
+      <pre><code>@import "@syncedco/flow/styles.css";</code></pre>
+      <h2 id="tokens">Tokens</h2>
+      <p>Use <code>--sf-*</code> variables for stable project styling.</p>
+      <h2 id="components">Components</h2>
+      <p>Compose cards, buttons, forms, alerts, and website patterns from public <code>sf-*</code> classes.</p>
+    </article>
+  </div>
+</main>
+```
+
+## Contact Or Lead Form
+
+```html
+<section class="sf-section" id="contact">
+  <div class="sf-container sf-split">
+    <div class="sf-stack">
+      <p class="sf-kicker">Contact</p>
+      <h2 class="sf-text-h2">Collect a lead with accessible states included.</h2>
+      <p class="sf-prose">Labels, help text, required markers, invalid states, and submit buttons share the same token system.</p>
+    </div>
+    <form class="sf-card sf-form" action="#" method="post">
+      <div class="sf-field">
+        <label class="sf-required" for="name">Name</label>
+        <input class="sf-input" id="name" name="name" required aria-describedby="name-help" />
+        <p class="sf-help" id="name-help">Your name is required.</p>
+      </div>
+      <div class="sf-field" data-invalid="true">
+        <label class="sf-required" for="email">Email</label>
+        <input class="sf-input" id="email" name="email" type="email" required aria-invalid="true" aria-describedby="email-help email-error" />
+        <p class="sf-help" id="email-help">Use a work email address.</p>
+        <p class="sf-error" id="email-error">Enter a valid email address.</p>
+      </div>
+      <button class="sf-button" type="submit">Send enquiry</button>
+    </form>
+  </div>
+</section>
+```
+
+## Lightweight App Shell
+
+```html
+<div class="sf-section sf-bg-surface-alt">
+  <div class="sf-container sf-stack">
+    <header class="sf-repel">
+      <div>
+        <p class="sf-kicker">Workspace</p>
+        <h1 class="sf-text-h2">Project dashboard</h1>
+      </div>
+      <button class="sf-button sf-button--secondary" type="button" aria-pressed="false">Filter</button>
+    </header>
+    <div class="sf-panel-grid">
+      <article class="sf-card">
+        <h2 class="sf-card__title">Pipeline</h2>
+        <p class="sf-card__description">Review the current work queue.</p>
+      </article>
+      <article class="sf-card">
+        <h2 class="sf-card__title">Messages</h2>
+        <p class="sf-card__description">Keep client updates visible.</p>
+      </article>
+      <article class="sf-alert sf-alert--info" role="status">
+        <p class="sf-alert__title">Sync complete</p>
+        <p>The workspace is up to date.</p>
+      </article>
+    </div>
+  </div>
+</div>
+```
+
+## Pricing And FAQ
+
+```html
+<section class="sf-section" id="pricing">
+  <div class="sf-container sf-stack">
+    <header class="sf-section-header">
+      <p class="sf-kicker">Pricing</p>
+      <h2 class="sf-text-h2">Commercial sections use the same primitives.</h2>
+    </header>
+    <div class="sf-pricing-grid">
+      <article class="sf-price-card">
+        <h3>Starter</h3>
+        <p class="sf-price"><span class="sf-price__value">£0</span> <span class="sf-price__interval">prototype</span></p>
+        <a class="sf-button sf-button--outline" href="/start">Try it</a>
+      </article>
+      <article class="sf-price-card sf-price-card--featured">
+        <p class="sf-badge">Most useful</p>
+        <h3>Website</h3>
+        <p class="sf-price"><span class="sf-price__value">£49</span> <span class="sf-price__interval">project</span></p>
+        <a class="sf-button" href="/start">Start</a>
+      </article>
+    </div>
+    <div class="sf-faq">
+      <details class="sf-faq__item">
+        <summary>Can I customize the theme?</summary>
+        <p>Yes. Override semantic tokens before writing custom CSS.</p>
+      </details>
+    </div>
+  </div>
+</section>
+```

package/docs/release-readiness.md

@@ -0,0 +1,63 @@
+# Release Readiness
+
+Use this checklist before tagging or publishing Synced Flow.
+
+## Lean Package Checks
+
+- `package.json` has no runtime dependencies.
+- `styles.css` stays below the gzip budget in `scripts/guardrails.mjs`.
+- `components.css`, `layout.css`, `utilities.css`, and `tokens.css` stay below
+  their gzip budgets.
+- New CSS uses existing tokens before introducing new variables.
+- New classes are broad primitives or common website patterns, not project
+  one-offs.
+
+## CSS System Checks
+
+- Type and spacing use Utopia-style `clamp()` tokens.
+- Fixed dimensions use `rem`.
+- Raw `px` appears only for allowed hairlines or forced-colors fallbacks.
+- Reset, base, app, layout, components, and utilities remain separate layer
+  files.
+- `styles.css` is generated from the same layer sources and does not duplicate
+  reset/base content.
+
+## Accessibility Confidence Pass
+
+Synced Flow does not run audits for consuming projects, but the package should
+keep the CSS affordances in place.
+
+- Keyboard focus is visible on links, buttons, form fields, summaries, and
+  skip links.
+- `aria-current`, `aria-expanded`, `aria-pressed`, `aria-selected`,
+  `aria-disabled`, `aria-busy`, and `aria-invalid` have visible states where
+  the system provides matching primitives.
+- Native disabled, required, invalid, `details[open]`, and `:target` states are
+  styled.
+- 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.
+
+## Documentation Checks
+
+- README points to the main docs.
+- Quick start explains the import choices.
+- System primitives lists current tokens/classes.
+- CSS API contract explains public vs internal surfaces.
+- Recipes show how to build common pages without one-off CSS.
+- CSS optimisation docs include current measured sizes.
+
+## Commands
+
+```bash
+pnpm build
+pnpm check
+pnpm test
+node bin/synced-flow.mjs tokens --json
+node bin/synced-flow.mjs catalog --json
+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.

package/docs/system-primitives.md

@@ -0,0 +1,150 @@
+# System Primitives
+
+Synced Flow is meant to cover the common styling decisions needed for a basic
+modern website before a developer reaches for project-specific CSS.
+
+## Token Layers
+
+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. |
+| 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. |
+| 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. |
+| Accessibility | `:focus-visible`, `:target`, `[aria-invalid]`, `[aria-current]`, `[aria-expanded]`, `[aria-selected]`, `[aria-busy]`, `[aria-disabled]` | Visible native and ARIA states. |
+
+Light and dark modes can be applied with `.sf-theme-light`,
+`[data-sf-theme="light"]`, `.sf-theme-dark`, or `[data-sf-theme="dark"]`.
+
+## Layout Classes
+
+These classes are the first choice for page structure.
+
+| Class | Purpose |
+| --- | --- |
+| `sf-container` | Fluid max-width wrapper with tokenized gutters. |
+| `sf-container--narrow`, `sf-container--wide`, `sf-container--full` | Container width variants. |
+| `sf-section`, `sf-section--compact`, `sf-section--spacious` | Vertical section rhythm. |
+| `sf-stack`, `sf-stack--tight`, `sf-stack--loose` | Vertical spacing between children. |
+| `sf-flow` | Adds block flow spacing between prose-like children. |
+| `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-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. |
+| `sf-frame`, `sf-frame--square`, `sf-frame--portrait`, `sf-frame--wide` | Stable media aspect ratios. |
+| `sf-cover`, `sf-hero` | Full-height and hero section structure. |
+| `sf-scroll-viewport`, `sf-scroll-panel`, `sf-scroll-snap-y`, `sf-sticky-top`, `sf-media-object`, `sf-aside-rail` | Scroll, sticky, and intent-based layout modes. |
+
+## Component Classes
+
+These cover the common UI elements needed for a simple site.
+
+| Class | Purpose |
+| --- | --- |
+| `sf-button` | Base button/link button. |
+| `sf-button--default`, `sf-button--secondary`, `sf-button--outline`, `sf-button--ghost`, `sf-button--link`, `sf-button--destructive` | Button variants. |
+| `sf-button--sm`, `sf-button--lg`, `sf-button--icon`, `sf-icon-button`, `sf-button--block` | Button sizing and width. |
+| `sf-button-group` | Wrapped action group. |
+| `sf-icon`, `sf-icon--xs`, `sf-icon--sm`, `sf-icon--md`, `sf-icon--lg`, `sf-icon--xl` | Fluid, currentColor SVG icon sizing for Lucide, Heroicons, Bootstrap Icons, or inline SVG. |
+| `sf-card`, `sf-card--flat`, `sf-card--raised`, `sf-card--interactive` | Card surfaces. |
+| `sf-card__header`, `sf-card__body`, `sf-card__footer`, `sf-card__title`, `sf-card__description` | Card structure. |
+| `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-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-disclosure`, `sf-accordion` | Native `details`/`summary` disclosure patterns. |
+| `sf-tabs`, `sf-tab-list`, `sf-tab`, `sf-tab-panel` | HTML/CSS-first tab styling. |
+| `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-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. |
+
+## Utility Classes
+
+Use utility classes for small decisions that do not need a new component.
+
+| Class | Purpose |
+| --- | --- |
+| `sf-text-caption`, `sf-text-body`, `sf-text-lead`, `sf-text-h4`, `sf-text-h3`, `sf-text-h2`, `sf-text-h1`, `sf-text-display` | Fluid text scale. |
+| `sf-text-muted`, `sf-text-subtle`, `sf-text-primary`, `sf-text-success`, `sf-text-warning`, `sf-text-danger` | Semantic text colour. |
+| `sf-bg-background`, `sf-bg-surface`, `sf-bg-surface-alt`, `sf-bg-primary-soft`, `sf-bg-success-soft`, `sf-bg-warning-soft`, `sf-bg-danger-soft` | Semantic backgrounds. |
+| `sf-border`, `sf-border-strong`, `sf-rounded`, `sf-rounded-panel`, `sf-rounded-full` | Border and radius helpers. |
+| `sf-shadow-sm`, `sf-shadow-md`, `sf-shadow-lg`, `sf-shadow-none` | Shadow helpers. |
+| `sf-push-block-end`, `sf-push-block-start`, `sf-push-inline-end`, `sf-push-inline-start` | Auto-margin positioning helpers for pushing items to an edge inside flex/grid layouts. |
+| `sf-prose`, `sf-text-balance`, `sf-text-pretty` | Content width and wrapping helpers. |
+| `sf-prose--blog`, `sf-prose--legal`, `sf-meta`, `sf-figure`, `sf-caption`, `sf-table-wrap` | Long-form content and article helpers. |
+| `sf-link`, `sf-link-subtle`, `sf-link-plain` | Link treatments. |
+| `sf-list-reset`, `sf-list-disc`, `sf-list-decimal` | List treatments. |
+| `sf-skip-link`, `sf-focus-ring`, `sf-focus-ring-inset`, `sf-touch-target`, `sr-only`, `not-sr-only` | Accessibility helpers. |
+| `sf-animate-fade`, `sf-animate-rise`, `sf-animate-scale`, `sf-animate-slide`, `sf-animate-stagger` | Reduced-motion-safe motion primitives. |
+
+## Example
+
+```html
+<button class="sf-button">
+  <svg class="sf-icon" aria-hidden="true" viewBox="0 0 24 24">...</svg>
+  Settings
+</button>
+
+<button class="sf-button sf-button--ghost sf-icon-button" aria-label="Settings">
+  <svg class="sf-icon sf-icon--lg" aria-hidden="true" viewBox="0 0 24 24">...</svg>
+</button>
+```
+
+```tsx
+import { Settings } from "lucide-react"
+
+export function SettingsButton() {
+  return (
+    <button className="sf-button">
+      <Settings className="sf-icon" aria-hidden="true" />
+      Settings
+    </button>
+  )
+}
+```
+
+```html
+<section class="sf-section">
+  <div class="sf-container sf-split">
+    <div class="sf-stack">
+      <p class="sf-badge">Fluid by default</p>
+      <h1 class="sf-text-display">Build from reusable CSS primitives.</h1>
+      <p class="sf-text-lead sf-text-muted sf-prose">
+        Start with tokens, layout classes, and components before writing custom CSS.
+      </p>
+      <div class="sf-button-group">
+        <a class="sf-button sf-button--default" href="/contact">Start a project</a>
+        <a class="sf-button sf-button--outline" href="/docs">Read docs</a>
+      </div>
+    </div>
+
+    <form class="sf-surface sf-form">
+      <div class="sf-field">
+        <label for="email">Email</label>
+        <input class="sf-input" id="email" type="email" />
+      </div>
+      <button class="sf-button sf-button--block" type="submit">Send</button>
+    </form>
+  </div>
+</section>
+```
+
+See `examples/plain-html` for a complete page using the same primitives.
+
+For copy-ready section patterns, see [Website patterns](website-patterns.md).
+For native browser component patterns, see [Native Components](native-components.md).
+For accessibility state hooks, see [Accessibility CSS](accessibility-css.md).
+For public API stability rules, see [CSS API Contract](api-contract.md).

package/docs/tailwind-comparison.md

@@ -0,0 +1,66 @@
+# Tailwind Migration Context
+
+Tailwind CSS is referenced here only to help teams migrate existing projects.
+Synced Flow is an independent fluid CSS system, not a Tailwind copy,
+compatibility layer, or one-for-one feature replacement.
+
+## Developer Expectations During Migration
+
+Teams coming from Tailwind often expect a short install flow, a CLI, generated
+CSS from source files, clear framework setup, safelisting for dynamic class
+names, and setup diagnostics. Synced Flow supports those expectations while
+using its own fluid, token-led styling model.
+
+| Migration expectation | Synced Flow direction |
+| --- | --- |
+| Install a package, import one stylesheet, start building | `pnpm add @syncedco/flow`, `synced-flow init`, import the generated CSS entry |
+| CLI builds CSS from scanned source files | `synced-flow build` scans configured project folders and writes generated utility CSS |
+| Framework-specific setup docs | `synced-flow init --preset next/vite/astro/plain` |
+| Theme variables as the styling API | CSS custom properties in `@syncedco/flow/styles.css` plus project overrides |
+| Source registration and monorepo-friendly paths | `scan` and `cwd` config options |
+| Safelisting for dynamic class names | `safelist` config option and `--safelist` CLI flag |
+| Setup diagnostics | `synced-flow doctor` |
+
+## How Synced Flow Differs
+
+Synced Flow starts with a fluid design system rather than a breakpoint-first
+utility framework. New projects keep `responsiveVariants` off, then use fluid
+type, spacing, layout primitives, and container-aware component CSS.
+
+For CSS size, Synced Flow favours modular layer imports and source-scanned
+utility generation rather than shipping a large universal utility file. See
+[CSS optimisation](css-optimisation.md) for current size measurements and
+marketing-safe claims.
+
+Responsive variants such as `sm:` and `lg:` are available only as an explicit
+migration option:
+
+```js
+export default defineConfig({
+  scan: ['app', 'components', 'lib'],
+  out: 'app/synced-flow.generated.css',
+  responsiveVariants: true,
+})
+```
+
+## Migration Docs Should Keep
+
+- `init` should get a project compiling quickly.
+- `build --check` should fail CI when generated CSS is stale.
+- `doctor` should explain missing imports, config, scripts, and stale setup.
+- Docs should show copy-pasteable install paths for common frameworks.
+- Scanner docs must clearly explain dynamic class limits.
+- Token docs should show the primitive, semantic, and component layers.
+
+## References For Migration Planning
+
+- Tailwind's Vite guide shows the value of a short install/import/start flow:
+  https://tailwindcss.com/docs/installation/using-vite
+- Tailwind's CLI guide shows the expected build/watch mental model:
+  https://tailwindcss.com/docs/installation/tailwind-cli
+- Tailwind's source detection docs explain scanner behaviour, explicit source
+  paths, and safelisting:
+  https://tailwindcss.com/docs/detecting-classes-in-source-files
+- Tailwind's theme variable docs show why tokens should be the public styling
+  API:
+  https://tailwindcss.com/docs/theme

package/docs/tokens.md

@@ -0,0 +1,79 @@
+# Tokens Guide
+
+Synced Flow uses a three-layer token model.
+
+```text
+Primitive -> Semantic -> Component
+```
+
+## Primitive
+
+Primitive tokens hold raw design values.
+
+```css
+--sf-colour-orange-600: oklch(68% 0.18 44);
+--sf-radius-md: 0.5rem;
+--sf-font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+```
+
+## Semantic
+
+Semantic tokens describe intent.
+
+```css
+--sf-colour-background: var(--sf-colour-neutral-50);
+--sf-colour-foreground: var(--sf-colour-neutral-900);
+--sf-colour-primary: var(--sf-colour-orange-600);
+--sf-colour-surface-raised: var(--sf-colour-neutral-0);
+--sf-colour-success-soft: oklch(62% 0.13 150 / 0.12);
+```
+
+Use semantic utilities in projects:
+
+```html
+<section class="bg-background text-foreground">
+  <a class="sf-button sf-button--default">Book a call</a>
+</section>
+```
+
+## Component
+
+Component tokens define reusable component defaults.
+
+```css
+--sf-button-radius: var(--sf-radius-md);
+--sf-button-block-size: 2.75rem;
+--sf-card-padding: var(--sf-space-m-l);
+--sf-input-padding-inline: var(--sf-space-s);
+--sf-alert-padding: var(--sf-space-s-m);
+--sf-nav-gap: var(--sf-space-xs-s);
+```
+
+## Fluid Scale
+
+Type and space tokens use Utopia-style `clamp()` values.
+
+```css
+--sf-step-0: clamp(1rem, 0.9617rem + 0.1701vw, 1.125rem);
+--sf-space-s-l: clamp(1rem, 0.6173rem + 1.7007vw, 2.25rem);
+```
+
+Prefer these tokens for new project CSS instead of fixed pixel values.
+
+## Core Starter Tokens
+
+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-inset`
+- text and links: `--sf-colour-foreground`, `--sf-colour-muted`,
+  `--sf-colour-subtle`, `--sf-colour-link`, `--sf-colour-link-hover`
+- actions: `--sf-colour-primary`, `--sf-colour-primary-hover`,
+  `--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`,
+  `--sf-radius-control`, `--sf-radius-panel`, `--sf-shadow-*`
+
+For class-level usage, see [System primitives](system-primitives.md).