@syncedco/flow 0.1.0

package/docs/build-a-site-walkthrough.md

@@ -0,0 +1,122 @@
+# Build A Site Walkthrough
+
+This walkthrough shows the intended real-world flow for a new website: theme
+decisions first, then recipes, then verification.
+
+## 1. Install And Initialise
+
+```bash
+pnpm add @syncedco/flow
+pnpm exec synced-flow init --preset next --theme synced --agents
+```
+
+Use the closest preset: `next`, `astro`, `vite`, `wordpress`, or `plain`.
+For WordPress, see [WordPress](wordpress.md) and the
+[`examples/wordpress`](../examples/wordpress) template.
+
+`--agents` adds a project-level `AGENTS.md` Synced Flow section so AI coding
+agents can find the packaged skill and the right CLI checks. Existing projects
+can run `pnpm exec synced-flow agents install`.
+
+## 2. Write A Theme Brief
+
+Create `brief.md`:
+
+```md
+Modern B2B SaaS site.
+Radius: slightly rounded, not pill shaped.
+Fonts: Inter/system UI with clean display headings.
+Primary colour: blue.
+Accent colour: green.
+Surface style: raised cards.
+Density: spacious sections.
+```
+
+Generate a validated theme block:
+
+```bash
+pnpm exec synced-flow theme init --from brief.md --preset-base neutral-saas
+```
+
+If the brief misses decisions such as radius, fonts, primary colour, accent
+colour, surface style, or density, the command prints warnings and fills
+sensible defaults. Paste the generated `theme` block into
+`synced-flow.config.mjs`.
+
+## 3. Pick A Recipe
+
+Ask Synced Flow for matching recipes:
+
+```bash
+pnpm exec synced-flow suggest "SaaS landing page with pricing and FAQ"
+pnpm exec synced-flow suggest "scroll portfolio with contact" --scaffold --framework next --dry-run
+```
+
+Print copy-ready markup:
+
+```bash
+pnpm exec synced-flow recipe saas-landing --framework next --markup
+```
+
+For a single section:
+
+```bash
+pnpm exec synced-flow recipe --section form --framework next --markup
+```
+
+For interaction patterns such as mobile drawers or scroll panels:
+
+```bash
+pnpm exec synced-flow pattern --list
+pnpm exec synced-flow pattern mobile-nav-drawer --framework next --markup
+```
+
+Available page recipes include `saas-landing`, `portfolio-scroll`,
+`saas-dashboard`, `agency-home`, `blog-index`, `article-page`,
+`about-timeline`, `team-grid`, `contact-page`, `not-found`, and
+`coming-soon`.
+
+Choose `saas-landing` for public SaaS marketing pages. Choose
+`saas-dashboard` for authenticated app screens with login/account state,
+workspace navigation, metrics, tables, and activity panels.
+
+## 4. Edit Content, Not CSS
+
+Replace headings, links, images, prices, and form fields in the recipe markup.
+Keep the `sf-*` structure where possible:
+
+- layout: `sf-container`, `sf-section`, `sf-stack`, `sf-split`, `sf-auto-grid`
+- components: `sf-button`, `sf-card`, `sf-form`, `sf-nav`, `sf-disclosure`
+- content: `sf-prose`, `sf-meta`, `sf-figure`, `sf-table-wrap`
+
+Use `synced-flow catalog --json` when an AI agent needs the full public API.
+Use `synced-flow pattern <id> --json` when it needs accessibility notes,
+gotchas, and framework-specific markup for native interactions.
+
+## 5. Build And Verify
+
+```bash
+pnpm flow:build
+pnpm flow:check
+pnpm exec synced-flow lint --json
+pnpm flow:doctor
+```
+
+`lint` catches unsupported class tokens, suggests nearest alternatives, and
+warns about incomplete native interaction composition such as drawers without
+close paths or dynamic class fragments.
+`doctor` checks setup, generated CSS freshness, theme shape, duplicate imports,
+ad hoc token overrides, AI guidance, and release-facing guardrails.
+
+## 6. Keep It Lean
+
+Use the full core import while building:
+
+```css
+@import "@syncedco/flow/styles.css";
+@import "./synced-flow.generated.css";
+```
+
+For tighter loading, switch to modular imports only if the project has a clear
+reason to omit a layer. Do not import `styles.css` and modular core files
+together.

package/docs/cli-reference.md

@@ -0,0 +1,230 @@
+# CLI Reference
+
+## init
+
+Scaffold Synced Flow into a project.
+
+```bash
+pnpm exec synced-flow init --preset next
+```
+
+Options:
+
+| Option | Purpose |
+| --- | --- |
+| `--preset next` | Next.js app or pages project. |
+| `--preset vite` | Vite React project. |
+| `--preset astro` | Astro project. |
+| `--preset wordpress` | WordPress theme or plugin with enqueue-ready CSS output. |
+| `--preset plain` | Plain HTML/CSS project. |
+| `--agents <target>` | Install project-level AI guidance after init. Omit the value for `universal`. |
+| `--theme <name>` | Use `synced`, `neutral-saas`, `editorial`, or `dark-app`. |
+| `--scan <dir>` | Add source directories. |
+| `--out <file>` | Choose generated CSS output path. |
+| `--safelist <classes>` | Add always-generated classes. |
+| `--include-core` | Write a single CSS output that includes tokens, reset, base, layout, and components. |
+| `--defaults` / `--no-defaults` | Include or exclude optional site/UI defaults during init. |
+| `--responsive-variants` | Enable migration support for `sm:`/`lg:` classes. |
+| `--no-scripts` | Do not update `package.json`. |
+| `--force` | Overwrite init-managed files. |
+
+## agents
+
+Install or inspect project-level AI guidance.
+
+```bash
+pnpm exec synced-flow agents install
+pnpm exec synced-flow agents install --target all
+pnpm exec synced-flow agents install --target cursor --dry-run
+pnpm exec synced-flow agents status
+```
+
+Targets are `universal`, `cursor`, `codex`, `claude`, `copilot`, `windsurf`,
+`gemini`, `aider`, and `all`. The default target is `universal`, which writes a
+managed Synced Flow section to `AGENTS.md`. Tool-specific targets add
+project-local instruction or skill files where the tool supports them.
+
+Use `--force` to refresh managed guidance and `--dry-run` to preview writes.
+
+## skill
+
+Print the packaged Synced Flow skill location and the project setup commands.
+
+```bash
+pnpm exec synced-flow skill
+```
+
+## add defaults
+
+Add the optional site/UI defaults import to an existing CSS entry.
+
+```bash
+pnpm exec synced-flow add defaults --file src/synced-flow.css
+```
+
+If `--file` is omitted, the CLI looks for the CSS entry created by `init`.
+
+## build
+
+Generate project utility CSS.
+
+```bash
+pnpm exec synced-flow build
+pnpm exec synced-flow build --check
+```
+
+Use `--check` in CI to fail when the generated file is stale.
+
+Generated CSS only includes source-scanned utility classes, configured theme
+overrides, and keyframes needed by scanned animation classes.
+
+## watch
+
+Run `build`, then rebuild when configured scan files change.
+
+```bash
+pnpm exec synced-flow watch
+```
+
+`watch` uses the same config and options as `build`. It is a small development
+loop helper and does not add a bundler or runtime dependency.
+
+## lint
+
+Scan configured source files and report unsupported class tokens with nearest
+public Synced Flow alternatives. It also reports composition warnings for
+common AI-generated structural mistakes.
+
+```bash
+pnpm exec synced-flow lint
+pnpm exec synced-flow lint --json
+pnpm exec synced-flow lint --json src components
+```
+
+Use this before handoff when an AI agent or template generator has composed
+markup. It catches misspelled generated utilities such as `text-prmary` and
+unknown `sf-*` classes such as `sf-buton`.
+
+Composition rules include `popover-missing-close`, `mobile-nav-incomplete`,
+`dynamic-class-fragment`, `invalid-popover-on-anchor`,
+`theme-override-in-css`, and `unknown-generated-utility`. JSON output returns
+`ok` and an `issues[]` array with `rule`, `severity`, `file`, `line`,
+`message`, and `fix`. `--fix` is accepted for forward compatibility; current
+composition rules provide guided fixes rather than rewriting source.
+
+## doctor
+
+Inspect project setup.
+
+```bash
+pnpm exec synced-flow doctor
+pnpm exec synced-flow validate
+```
+
+Checks include package installation, package scripts, config, generated CSS,
+core stylesheet import, lint status, theme shape, duplicate core imports,
+ad hoc token overrides, Tailwind residue, AI agent guidance, and whether strict
+fluid mode is on.
+
+`validate` is an alias for `doctor`.
+
+## tokens
+
+Print supported tokens, presets, and starter classes.
+
+```bash
+pnpm exec synced-flow tokens
+pnpm exec synced-flow tokens --json
+```
+
+Use `--json` when an AI agent or generator needs a machine-readable map.
+
+## catalog
+
+Print the public API catalog: CSS files, commands, tokens, classes, native
+component patterns, recipes, and guardrails.
+
+```bash
+pnpm exec synced-flow catalog
+pnpm exec synced-flow catalog --json
+```
+
+Use `catalog --json` when an AI agent needs to choose the right recipe or class
+surface before writing markup.
+
+## suggest
+
+Return matching recipes and classes for a short site or section brief.
+
+```bash
+pnpm exec synced-flow suggest "full page scroll portfolio"
+pnpm exec synced-flow suggest "native drawer menu and contact form" --json
+pnpm exec synced-flow suggest "scroll portfolio" --scaffold --framework next --dry-run
+```
+
+JSON output includes matching section patterns and full-page recipes. Use the
+recipe id with `recipe` when an agent needs copy-ready markup.
+
+With `--scaffold`, Synced Flow prints or writes a minimal starter for
+`next`, `vite`, `astro`, or `plain`. Use `--out <dir>` to choose the project
+directory, `--dry-run` to print the file tree and contents, and `--force` to
+overwrite scaffold-managed files.
+
+## pattern
+
+List or print copy-ready interaction patterns.
+
+```bash
+pnpm exec synced-flow pattern --list
+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
+classes, framework markup, JS requirement notes, accessibility notes, and
+implementation gotchas.
+
+## recipe
+
+List or print page-level recipes.
+
+```bash
+pnpm exec synced-flow recipe
+pnpm exec synced-flow recipe saas-landing
+pnpm exec synced-flow recipe portfolio-scroll --markup
+pnpm exec synced-flow recipe portfolio-scroll --framework next --markup
+pnpm exec synced-flow recipe --section hero --framework astro --markup
+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
+are intended as copy-paste starting points rather than new utility APIs.
+
+Use `--framework html`, `--framework next`, `--framework react`, or
+`--framework astro` to adapt markup. Use `--section <id-or-keyword>` to print a
+single section pattern such as `hero`, `scroll`, `tabs`, or `form`.
+
+## theme
+
+Create or validate theme tokens without scattering brand decisions through page
+CSS.
+
+```bash
+pnpm exec synced-flow theme init --from brief.md
+pnpm exec synced-flow theme init --from brief.md --preset-base neutral-saas
+pnpm exec synced-flow theme init --from brief.md --json
+pnpm exec synced-flow theme validate
+```
+
+`theme init --from` reads a simple brief for radius, fonts, colours, card style,
+and density, then prints a validated `theme` block for
+`synced-flow.config.mjs`. `theme validate` checks the configured theme shape.
+Use `--preset-base synced`, `--preset-base neutral-saas`,
+`--preset-base editorial`, or `--preset-base dark-app` to inherit a starting
+preset before applying brief-derived overrides.

package/docs/config-reference.md

@@ -0,0 +1,81 @@
+# Config Reference
+
+Create `synced-flow.config.mjs` in the project root.
+
+```js
+import { defineConfig } from '@syncedco/flow/config'
+import { themePresets } from '@syncedco/flow/presets'
+
+export default defineConfig({
+  scan: ['src', 'components'],
+  out: 'src/synced-flow.generated.css',
+  responsiveVariants: false,
+  includeDefaults: true,
+  safelist: [],
+  theme: themePresets.synced,
+})
+```
+
+## Options
+
+| Option | Type | Purpose |
+| --- | --- | --- |
+| `cwd` | `string` | Resolve scan and output paths from a specific directory. |
+| `scan` | `string[]` | Source directories scanned for complete class tokens. |
+| `safelist` | `string[]` | Class tokens to always generate for dynamic class cases. |
+| `out` | `string` | Generated CSS output path. |
+| `includeCore` | `boolean` | Include reset/base/layout/component CSS in generated output. |
+| `includeDefaults` | `boolean` | Include optional site/UI defaults when `includeCore` is true. |
+| `responsiveVariants` | `boolean` | Enable `sm:`, `md:`, `lg:`, `xl:` compatibility variants. |
+| `failOnUnsupported` | `boolean` | Fail when unsupported class tokens are detected. |
+| `quiet` | `boolean` | Suppress non-critical warnings. |
+| `theme` | `object` | Project token overrides emitted into generated CSS. |
+
+Set `includeCore: true` for environments that enqueue a plain CSS file and do
+not process npm CSS imports, such as many WordPress themes and plugins.
+Set `includeDefaults: true` with `includeCore` when that single generated file should
+also remove raw link underlines and list markers for site/UI surfaces.
+
+## Theme
+
+Theme values become CSS custom properties in the generated file. Synced Flow
+emits both the public `--sf-*` token and the utility-compatible alias where
+needed.
+
+```js
+theme: {
+  fonts: {
+    sans: 'Inter, ui-sans-serif, system-ui, sans-serif',
+    display: 'Fraunces, Georgia, serif',
+    mono: '"SF Mono", ui-monospace, monospace',
+  },
+  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)',
+    primaryForeground: 'oklch(100% 0 0)',
+    border: 'oklch(18% 0.026 250 / 0.12)',
+  },
+  darkColours: {
+    background: 'oklch(13.5% 0.03 252)',
+    foreground: 'oklch(96% 0.008 86)',
+  },
+  radii: {
+    md: '0.5rem',
+    lg: '0.75rem',
+  },
+  layout: {
+    containerMax: '72rem',
+    gutter: 'var(--space-s-l)',
+    columns: 12,
+  },
+  components: {
+    button: {
+      radius: 'var(--radius-md)',
+      blockSize: '2.75rem',
+      paddingInline: 'var(--space-s)',
+    },
+  },
+}
+```

package/docs/css-optimisation.md

@@ -0,0 +1,117 @@
+# CSS Optimisation Notes
+
+Current measurements from `pnpm build` on 2026-05-24.
+
+## Developer Notes
+
+Synced Flow keeps CSS loading small through three mechanisms:
+
+- modular CSS layer exports for projects that do not need the full core file
+- source-scanned utility generation, so project utility CSS is generated from
+  discovered class tokens instead of shipping every possible utility
+- conditional generated helpers, so animation keyframes are emitted only when
+  scanned classes such as `animate-pulse` or `animate-spin` need them
+
+The core stylesheet is intentionally built with modern CSS best practices:
+cascade layers for predictable ordering, CSS custom properties for theming,
+fluid `clamp()` scales, logical properties for writing-mode-friendly layout,
+OKLCH colour tokens, container-aware layout primitives, and
+`prefers-reduced-motion` safeguards.
+
+CSS is not tree-shaken like JavaScript by default. The practical optimisation
+model is to import only the layers a project needs, then let
+`synced-flow build` generate project-specific utility CSS.
+
+Choose either the bundled core stylesheet or modular layer imports. Do not
+import `styles.css` alongside `tokens.css`, `reset.css`, `base.css`,
+`layout.css`, `components.css`, or `utilities.css`, because `styles.css`
+already contains those layers.
+
+## Current CSS Sizes
+
+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. |
+
+Example generated project CSS with tokens plus one scanned `text-primary`
+utility measured 7,031 B raw and 1,943 B gzip.
+
+## Import Choices
+
+Use the full stylesheet when simplicity matters:
+
+```css
+@import "@syncedco/flow/styles.css";
+@import "./synced-flow.generated.css";
+```
+
+Use layer imports instead when a project wants a smaller core surface:
+
+```css
+@import "@syncedco/flow/tokens.css";
+@import "@syncedco/flow/reset.css";
+@import "@syncedco/flow/base.css";
+@import "@syncedco/flow/defaults.css";
+@import "@syncedco/flow/layout.css";
+@import "@syncedco/flow/components.css";
+@import "@syncedco/flow/utilities.css";
+@import "./synced-flow.generated.css";
+```
+
+Leave out `components.css` if the project only uses tokens and layout
+primitives. Leave out `defaults.css` when content-style browser affordances should
+stay intact. Leave out `utilities.css` unless the project uses static type,
+prose, accessibility, link, list, or full-bleed helpers.
+
+## WordPress
+
+Many WordPress themes and plugins enqueue plain CSS rather than resolving npm CSS
+imports through a bundler. Use the WordPress preset for that environment:
+
+```bash
+pnpm exec synced-flow init --preset wordpress
+pnpm flow:build
+```
+
+That preset scans PHP and template files, enables `includeCore`, and writes a
+single enqueue-ready file at `assets/css/synced-flow.css`.
+
+## Marketing Notes
+
+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.
+- Flexible loading: developers can import only the CSS layers their project
+  uses.
+- Source-scanned utilities: project utility CSS is generated from actual class
+  usage rather than shipping a large universal utility file.
+- WordPress-ready: themes and plugins can build one enqueue-ready CSS file.
+- Dependency-free runtime: the JavaScript entry currently ships without runtime
+  package dependencies.
+
+The package guardrail script enforces current gzip budgets:
+
+```bash
+pnpm guardrails
+```
+
+Budgets are intentionally tight enough to catch accidental bloat while leaving
+room for small improvements to the core primitives.
+
+Avoid claiming:
+
+- automatic CSS tree-shaking in every bundler
+- a full Tailwind feature replacement
+- fixed size guarantees, because CSS size changes as tokens and primitives
+  evolve

package/docs/migration-from-tailwind.md

@@ -0,0 +1,60 @@
+# Migration From Tailwind
+
+Synced Flow is not a one-for-one Tailwind replacement. The useful migration
+path is to keep class names complete, move project identity into tokens, and
+replace breakpoint-heavy layout with fluid primitives over time.
+
+## Package Setup
+
+Remove Tailwind packages when the project no longer needs them:
+
+```bash
+pnpm remove tailwindcss @tailwindcss/postcss @tailwindcss/vite tailwind-merge
+pnpm add @syncedco/flow
+pnpm exec synced-flow init
+```
+
+## Class Migration
+
+Start with compatibility utilities generated by `synced-flow build`, then move
+repeated layout patterns to Synced Flow primitives.
+
+| Tailwind-style pattern | Synced Flow direction |
+| --- | --- |
+| `container mx-auto px-6` | `sf-container` |
+| `py-16 sm:py-24` | `sf-section` or fluid space tokens |
+| `flex flex-col gap-4` | `sf-stack` |
+| `flex flex-wrap gap-3` | `sf-cluster` |
+| `grid gap-6 md:grid-cols-3` | `sf-auto-grid` or project CSS with `minmax()` |
+| `bg-primary text-primary-foreground` | Keep semantic utility classes |
+
+## Responsive Variants
+
+Use `responsiveVariants: true` only while migrating old code:
+
+```js
+export default defineConfig({
+  scan: ['app', 'components', 'lib'],
+  out: 'app/synced-flow.generated.css',
+  responsiveVariants: true,
+})
+```
+
+Turn it off for new projects and once layout has moved to fluid primitives.
+
+## Dynamic Classes
+
+Avoid building class names from fragments.
+
+```tsx
+// Good
+const states = {
+  open: 'block opacity-100',
+  closed: 'hidden opacity-0',
+}
+
+// Avoid
+const className = `${isOpen ? 'block' : 'hidden'} opacity-${amount}`
+```
+
+Use `safelist` when a dynamic class is unavoidable.