@syncedco/flow 0.1.0

package/defaults.css

@@ -0,0 +1,26 @@
+/* Generated by @syncedco/flow. Edit src/tokens.mjs or scripts/build-css.mjs, then run pnpm build. */
+@layer reset, tokens, base, app, layout, components, utilities;
+@layer app {
+  :where(a) {
+    color: inherit;
+    text-decoration: none;
+  }
+
+  :where(ol, ul, menu) {
+    list-style: none;
+    padding-inline-start: 0;
+  }
+
+  :where(button) {
+    background: transparent;
+    border: 0;
+    color: inherit;
+  }
+
+  :where(fieldset) {
+    border: 0;
+    padding: 0;
+  }
+
+  :where(legend) { padding: 0; }
+}

package/dist/config.d.ts

@@ -0,0 +1,94 @@
+type TokenMap = Record<string, string>;
+export type SyncedFlowTheme = {
+    /**
+     * Project font stacks. Values should be complete CSS font-family values.
+     */
+    fonts?: Partial<Record<'sans' | 'display' | 'mono', string>>;
+    /**
+     * Semantic colour tokens. Use OKLCH where possible.
+     */
+    colours?: TokenMap;
+    /**
+     * Semantic colour overrides for .sf-theme-dark or [data-sf-theme="dark"].
+     */
+    darkColours?: TokenMap;
+    /**
+     * Radius scale overrides such as md, lg, xl, full.
+     */
+    radii?: TokenMap;
+    /**
+     * Layout-level tokens.
+     */
+    layout?: {
+        containerMax?: string;
+        gutter?: string;
+        columns?: number;
+    };
+    /**
+     * Component-level token overrides.
+     */
+    components?: {
+        button?: {
+            radius?: string;
+            blockSize?: string;
+            paddingInline?: string;
+        };
+        card?: {
+            radius?: string;
+            padding?: string;
+            shadow?: string;
+        };
+        input?: {
+            radius?: string;
+            blockSize?: string;
+        };
+    };
+};
+export type SyncedFlowConfig = {
+    /**
+     * Directory used to resolve scan and output paths. Defaults to the current
+     * working directory.
+     */
+    cwd?: string;
+    /**
+     * Source directories that the CLI scans for class tokens.
+     */
+    scan?: string[];
+    /**
+     * Class tokens to always generate when they are composed dynamically.
+     */
+    safelist?: string[];
+    /**
+     * Generated CSS output file.
+     */
+    out?: string;
+    /**
+     * Project token overrides emitted into the generated CSS.
+     */
+    theme?: SyncedFlowTheme;
+    /**
+     * Include reset, base, layout, and component CSS in the generated file.
+     * Most projects should import @syncedco/flow/styles.css and leave this false.
+     */
+    includeCore?: boolean;
+    /**
+     * Include site/UI defaults when includeCore is true. For modular projects,
+     * import @syncedco/flow/defaults.css from the CSS entry instead.
+     */
+    includeDefaults?: boolean;
+    /**
+     * Enable breakpoint-style variants such as sm:, md:, lg:, and xl:.
+     * Leave false for strict fluid projects; enable only during migrations.
+     */
+    responsiveVariants?: boolean;
+    /**
+     * Fail the CLI when unsupported class tokens are detected.
+     */
+    failOnUnsupported?: boolean;
+    /**
+     * Suppress non-critical CLI warnings.
+     */
+    quiet?: boolean;
+};
+export declare function defineConfig(config: SyncedFlowConfig): SyncedFlowConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,3 @@
+export function defineConfig(config) {
+    return config;
+}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+export { defineConfig, type SyncedFlowConfig, type SyncedFlowTheme } from './config.js';
+export { presetNames, themePresets } from '../src/presets.mjs';
+export type ClassValue = string | number | boolean | null | undefined | ClassValue[] | Record<string, unknown>;
+export declare function cx(...inputs: ClassValue[]): string;
+export declare const fluidSystem: {
+    readonly layout: {
+        readonly container: "sf-container";
+        readonly section: "sf-section";
+        readonly stack: "sf-stack";
+        readonly cluster: "sf-cluster";
+        readonly repel: "sf-repel";
+        readonly grid: "sf-grid";
+        readonly autoGrid: "sf-auto-grid";
+        readonly sidebar: "sf-sidebar";
+        readonly switcher: "sf-switcher";
+        readonly frame: "sf-frame";
+        readonly cover: "sf-cover";
+        readonly flow: "sf-flow";
+    };
+    readonly components: {
+        readonly button: "sf-button";
+        readonly card: "sf-card";
+        readonly badge: "sf-badge";
+        readonly field: "sf-field";
+        readonly input: "sf-input";
+    };
+    readonly utilities: {
+        readonly visuallyHidden: "sf-visually-hidden";
+        readonly notVisuallyHidden: "sf-not-visually-hidden";
+        readonly srOnly: "sr-only";
+        readonly notSrOnly: "not-sr-only";
+        readonly skipLink: "sf-skip-link";
+        readonly focusRing: "sf-focus-ring";
+        readonly focusRingInset: "sf-focus-ring-inset";
+        readonly touchTarget: "sf-touch-target";
+        readonly listReset: "sf-list-reset";
+        readonly listDisc: "sf-list-disc";
+        readonly listDecimal: "sf-list-decimal";
+        readonly link: "sf-link";
+        readonly linkSubtle: "sf-link-subtle";
+        readonly linkPlain: "sf-link-plain";
+        readonly prose: "sf-prose";
+    };
+};
+export type FluidSystem = typeof fluidSystem;

package/dist/index.js

@@ -0,0 +1,67 @@
+export { defineConfig } from './config.js';
+export { presetNames, themePresets } from '../src/presets.mjs';
+export function cx(...inputs) {
+    const classes = [];
+    for (const input of inputs)
+        appendClassValue(classes, input);
+    return classes.join(' ');
+}
+function appendClassValue(classes, value) {
+    if (!value)
+        return;
+    if (typeof value === 'string' || typeof value === 'number') {
+        classes.push(String(value));
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            appendClassValue(classes, item);
+        return;
+    }
+    if (typeof value === 'object') {
+        for (const [className, enabled] of Object.entries(value)) {
+            if (enabled)
+                classes.push(className);
+        }
+    }
+}
+export const fluidSystem = {
+    layout: {
+        container: 'sf-container',
+        section: 'sf-section',
+        stack: 'sf-stack',
+        cluster: 'sf-cluster',
+        repel: 'sf-repel',
+        grid: 'sf-grid',
+        autoGrid: 'sf-auto-grid',
+        sidebar: 'sf-sidebar',
+        switcher: 'sf-switcher',
+        frame: 'sf-frame',
+        cover: 'sf-cover',
+        flow: 'sf-flow',
+    },
+    components: {
+        button: 'sf-button',
+        card: 'sf-card',
+        badge: 'sf-badge',
+        field: 'sf-field',
+        input: 'sf-input',
+    },
+    utilities: {
+        visuallyHidden: 'sf-visually-hidden',
+        notVisuallyHidden: 'sf-not-visually-hidden',
+        srOnly: 'sr-only',
+        notSrOnly: 'not-sr-only',
+        skipLink: 'sf-skip-link',
+        focusRing: 'sf-focus-ring',
+        focusRingInset: 'sf-focus-ring-inset',
+        touchTarget: 'sf-touch-target',
+        listReset: 'sf-list-reset',
+        listDisc: 'sf-list-disc',
+        listDecimal: 'sf-list-decimal',
+        link: 'sf-link',
+        linkSubtle: 'sf-link-subtle',
+        linkPlain: 'sf-link-plain',
+        prose: 'sf-prose',
+    },
+};

package/docs/accessibility-css.md

@@ -0,0 +1,133 @@
+# Accessibility CSS
+
+Synced Flow does not run accessibility audits. It provides CSS affordances so
+semantic HTML and ARIA states are visible, consistent, and easy to compose.
+
+## Principles
+
+- Prefer native elements first: `button`, `a[href]`, `label`, `input`,
+  `select`, `textarea`, `details`, `summary`, `nav`, `main`, `section`, and
+  `footer`.
+- Use ARIA only when native semantics do not express the state.
+- Keep accessible names and descriptions in markup; Synced Flow styles the
+  visible states.
+- Use project-level accessibility testing in the consuming app.
+
+## Built-In Affordances
+
+| Hook | Styled behavior |
+| --- | --- |
+| `:focus-visible` | Visible outline using `--sf-colour-ring`, with forced-colors support. |
+| `:target` | Scroll margin for skip links and anchor navigation. |
+| `.sf-skip-link` | Keyboard-visible skip link. |
+| `.sf-visually-hidden`, `.sr-only` | Visually hidden text that remains available to assistive tech. |
+| `.sf-touch-target` | Minimum interactive target sizing. |
+| `[aria-current="page"]`, `[aria-current="true"]` | Current nav/link state. |
+| `[aria-expanded="true"]`, `[aria-pressed="true"]`, `[aria-selected="true"]`, `[data-state="open"]` | Active disclosure/toggle/selection state for buttons and nav links. |
+| `[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-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. |
+
+## Forms
+
+Pair visible help and error text with `aria-describedby`. Use
+`aria-invalid="true"` only when a field is currently invalid.
+
+```html
+<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>
+```
+
+Use `disabled` for native disabled controls. Use `aria-disabled="true"` only
+when an element cannot use the native `disabled` attribute, such as an anchor
+that is visually present but intentionally unavailable.
+
+## Navigation And Disclosure
+
+Use `aria-current="page"` for the current page link.
+
+```html
+<nav class="sf-nav" aria-label="Primary">
+  <ul class="sf-nav__list">
+    <li><a class="sf-nav__link" href="/" aria-current="page">Home</a></li>
+    <li><a class="sf-nav__link" href="/pricing">Pricing</a></li>
+  </ul>
+</nav>
+```
+
+Use native `details`/`summary` for FAQ and simple disclosure content.
+
+```html
+<details class="sf-faq__item">
+  <summary>Can I customize the theme?</summary>
+  <p>Yes. Override semantic tokens before adding custom CSS.</p>
+</details>
+```
+
+For JavaScript-powered menus or toggles, use real buttons and update
+`aria-expanded`, `aria-pressed`, or `aria-selected` as appropriate. Synced Flow
+styles those states for `.sf-button` and `.sf-nav__link`.
+
+For native dialog, popover, drawer, tooltip, tabs, and disclosure markup, see
+[Native Components](native-components.md). Synced Flow styles those browser
+primitives but does not ship JavaScript components.
+
+## Alerts And Status
+
+Synced Flow alert variants are visual styles. Choose the live-region behavior
+in markup:
+
+```html
+<div class="sf-alert sf-alert--success" role="status">
+  <p class="sf-alert__title">Saved</p>
+  <p>Your changes were saved.</p>
+</div>
+
+<div class="sf-alert sf-alert--danger" role="alert">
+  <p class="sf-alert__title">Payment failed</p>
+  <p>Check the card details and try again.</p>
+</div>
+```
+
+Use `role="status"` for polite updates. Use `role="alert"` only for urgent
+messages that need immediate announcement.
+
+## Busy And Loading States
+
+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>
+```
+
+Synced Flow styles this as a busy state, but the consuming app should still
+manage focus, state changes, and completion messaging.
+
+## Confidence Checklist
+
+Use this when changing the CSS system or examples:
+
+- Navigate the demo with keyboard only.
+- Confirm focus is visible on links, buttons, form controls, summaries, and the
+  skip link.
+- Confirm invalid, required, disabled, busy, current, expanded, selected, and
+  pressed states remain visible when those states are present in markup.
+- Confirm `details`/`summary` works without JavaScript.
+- Confirm forced-colors styles do not depend only on subtle background colour.
+- Confirm examples use native elements before ARIA.

package/docs/ai-usage.md

@@ -0,0 +1,112 @@
+# AI Agent Setup And Usage
+
+Use this when an AI agent is building or editing a project with Synced Flow.
+
+Synced Flow ships a skill at
+[`skills/synced-flow/SKILL.md`](../skills/synced-flow/SKILL.md). In a
+consumer project, make it discoverable with project-level guidance:
+
+```bash
+pnpm exec synced-flow agents install
+pnpm exec synced-flow agents status
+pnpm exec synced-flow skill
+```
+
+Use `agents install --target all` to add project-local guidance for Cursor,
+Codex-style agents, Claude, Copilot, Windsurf, Gemini, and Aider where those
+tools have clear project conventions.
+
+## First Moves
+
+1. Install the package.
+2. Run `synced-flow init --preset <framework> --agents`.
+3. Ask for a short theme brief: radius, fonts, primary colour, accent colour,
+   surface style, and density.
+4. Convert that brief into `synced-flow.config.mjs` theme tokens.
+5. Import the generated CSS entry once.
+6. Run `synced-flow catalog --json` before choosing recipes and classes.
+7. Run `synced-flow pattern --list` before hand-rolling interaction markup.
+8. Run `synced-flow lint --json` and `synced-flow doctor` before finishing.
+
+Good theme prompt:
+
+```text
+Use the Synced Flow skill. Build a theme config for a modern B2B website:
+soft but not pill-shaped radius, system sans UI, editorial display headings,
+blue primary, green accent, light raised cards, and spacious sections.
+Return only the Synced Flow config theme object.
+```
+
+For a file-based workflow, put the answers in `brief.md` and run:
+
+```bash
+pnpm exec synced-flow theme init --from brief.md
+pnpm exec synced-flow theme init --from brief.md --preset-base neutral-saas
+```
+
+If the output includes warnings, ask the user for the missing brand decisions
+before finalising the theme.
+
+## Styling Rules
+
+- Prefer `sf-container`, `sf-section`, `sf-stack`, `sf-cluster`, `sf-auto-grid`,
+  `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.
+- Keep browser affordances unless the UI intentionally replaces them: body
+  links stay underlined, content lists keep markers, and focus states remain
+  visible.
+- Use `@syncedco/flow/defaults.css` for common site/UI defaults when raw links should
+  not be underlined and menu lists should not show bullets. Add it with
+  `synced-flow add defaults` if a project was initialised without it.
+- Use `sr-only` / `not-sr-only`, `sf-skip-link`, `sf-focus-ring`,
+  `sf-touch-target`, `sf-list-reset`, `sf-link`, and `sf-link-plain` for
+  accessibility and UI affordance work.
+- Use theme presets or config `theme` overrides for brand choices.
+- Put repeated brand decisions in theme tokens before adding custom CSS.
+- Use `synced-flow suggest "<brief>"` to choose section recipes before adding
+  new one-off patterns.
+- Use `synced-flow suggest "<brief>" --scaffold --framework <target> --dry-run`
+  when starting a page or project from a brief.
+- Use `synced-flow pattern <id> --markup` for complete native interaction
+  patterns such as mobile drawers, scroll sections, popover drawers, and native
+  dialogs.
+- Use `synced-flow recipe <id> --markup` to get copy-ready page sections for
+  SaaS, portfolio, agency, blog, article, about, team, contact, 404, and coming
+  soon pages.
+- 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.
+- 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.
+- Use `safelist` only when dynamic classes are unavoidable.
+- Do not enable `responsiveVariants` in new projects.
+
+## Good Starter Shape
+
+```html
+<main class="sf-section">
+  <section class="sf-container sf-stack">
+    <p class="sf-kicker">Practical systems</p>
+    <h1 class="sf-text-display">Fluid from the first screen.</h1>
+    <p class="sf-text-lead sf-prose">Use tokens and primitives before one-off CSS.</p>
+    <div class="sf-cluster">
+      <a class="sf-button sf-button--default" href="/contact">Start discovery</a>
+      <a class="sf-button sf-button--outline" href="/docs">Read docs</a>
+    </div>
+  </section>
+</main>
+```
+
+## Finish Checklist
+
+```bash
+pnpm flow:build
+pnpm flow:check
+pnpm exec synced-flow lint --json
+pnpm flow:doctor
+```
+
+If `doctor` warns about stale CSS, run `pnpm flow:build`.

package/docs/api-contract.md

@@ -0,0 +1,81 @@
+# CSS API Contract
+
+Synced Flow is small enough to read, but projects still need to know which
+parts are safe to rely on. Treat this page as the public CSS contract for the
+0.x line.
+
+## Stable Public Surface
+
+These are intended for application code and examples.
+
+| Surface | Public API |
+| --- | --- |
+| Imports | `@syncedco/flow/styles.css`, `tokens.css`, `reset.css`, `base.css`, `defaults.css`, `layout.css`, `components.css`, `utilities.css` |
+| Tokens | `--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-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` |
+| 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` |
+
+## AI Agent Contract
+
+The project-level AI setup commands are public in 0.x:
+
+- `synced-flow agents install [--target universal|cursor|codex|claude|copilot|windsurf|gemini|aider|all] [--force] [--dry-run]`
+- `synced-flow agents status`
+- `synced-flow skill`
+- `synced-flow pattern <id> [--framework html|next|react|astro] [--markup|--json]`
+- `synced-flow pattern --list`
+- `synced-flow suggest "<brief>" --scaffold [--framework next|vite|astro|plain] [--out dir] [--dry-run] [--force]`
+- `synced-flow lint [--json] [--fix] [paths...]`
+
+`catalog --json` includes `patterns[]` with copy-ready interaction metadata:
+classes, markup, JS requirement notes, accessibility notes, and gotchas.
+
+## Internal Or Compatibility Surface
+
+These can change more freely.
+
+- Generated compatibility utility selectors such as `[class~="text-primary"]`.
+- Tailwind-migration helpers enabled by `responsiveVariants`.
+- Implementation details inside `scripts/build-css.mjs`.
+- Utility-compatible aliases such as `--color-*`, `--font-*`, and `--radius-*`.
+  They are useful for migration output, but `--sf-*` tokens are the preferred
+  long-term API.
+
+## Unit Policy
+
+Design decisions should use `rem`, fluid `clamp()` tokens, logical properties,
+or percentages. Raw `px` is reserved for:
+
+- `1px` borders and inset hairlines.
+- Forced-colors/system fallback outlines.
+- Internal generator math that is emitted as `rem` or `clamp()`.
+
+`pnpm guardrails` enforces this policy against the shipped CSS files.
+
+## Change Rules
+
+- Additive tokens/classes are safe in minor releases.
+- Renaming or removing public `--sf-*` tokens or `sf-*` classes needs a
+  migration note and should wait for a major release once the project leaves
+  `0.x`.
+- New primitives should earn their place by replacing repeated website/app
+  CSS, not by chasing every utility class from larger frameworks.
+- Prefer documentation recipes before adding new CSS.
+
+## Stability Checklist
+
+Before changing the public surface, run:
+
+```bash
+pnpm build
+pnpm check
+pnpm test
+```
+
+`pnpm check` includes generated CSS freshness, type checks, CSS size budgets,
+dependency checks, layer-shape checks, and raw-pixel guardrails.

package/docs/base-styling.md

@@ -0,0 +1,113 @@
+# Base Styling Decisions
+
+Synced Flow uses a conservative reset and modern base layer. The goal is to
+make new projects consistent without hiding important browser affordances.
+
+## What Stays Native
+
+- Links stay visibly underlined by default.
+- `ul` and `ol` keep their markers by default.
+- Form controls inherit project typography but keep their native semantics.
+- Focus styles are visible through `:focus-visible`.
+- Headings, code, blockquotes, horizontal rules, and selection states get
+  token-based defaults without removing their native meaning.
+
+## Optional App Defaults
+
+Most app and marketing-site interfaces do not want raw link underlines in
+navigation, or bullets on menu lists. Add the optional defaults layer for those
+project-wide UI defaults:
+
+```css
+@import "@syncedco/flow/defaults.css";
+```
+
+You can also add it later with the CLI:
+
+```bash
+pnpm exec synced-flow add defaults --file src/synced-flow.css
+```
+
+`defaults.css` removes raw link underlines, resets `ol`/`ul`/`menu` markers and start
+padding, and strips basic button/fieldset chrome. Use `sf-link`, `sf-list-disc`,
+`sf-list-decimal`, or `sf-prose` where content needs visible semantics again.
+
+Use opt-in utilities when a component needs a different treatment:
+
+```html
+<nav aria-label="Primary">
+  <ul class="sf-list-reset sf-cluster">
+    <li><a class="sf-link-plain" href="/">Home</a></li>
+    <li><a class="sf-link-plain" href="/docs">Docs</a></li>
+  </ul>
+</nav>
+```
+
+## Accessibility Utilities
+
+```html
+<a class="sf-skip-link" href="#main">Skip to main content</a>
+<span class="sr-only">Opens in a new tab</span>
+<button class="sf-touch-target sf-focus-ring">Save</button>
+```
+
+Available helpers:
+
+- `sr-only` / `sf-visually-hidden`
+- `not-sr-only` / `sf-not-visually-hidden`
+- `sf-skip-link`
+- `sf-focus-ring`
+- `sf-focus-ring-inset`
+- `sf-touch-target`
+
+## Link Utilities
+
+- `sf-link` for primary inline links.
+- `sf-link-subtle` for inherited-colour inline links.
+- `sf-link-plain` for navigation, buttons, cards, and other UI where the
+  element has another clear affordance.
+
+Body and prose links should normally stay visibly identifiable.
+
+## Forms And UI Components
+
+The base layer keeps native form semantics, while component classes provide
+ready-to-use styling:
+
+```html
+<form class="sf-form">
+  <div class="sf-field">
+    <label for="email">Email</label>
+    <input class="sf-input" id="email" type="email" />
+    <p class="sf-help">We only use this for project updates.</p>
+  </div>
+  <button class="sf-button" type="submit">Send</button>
+</form>
+```
+
+Use `sf-input`, `sf-select`, `sf-textarea`, `sf-check`, `sf-help`, and
+`sf-error` for common form needs. Use `sf-alert` variants for notices and
+feedback.
+
+Synced Flow also styles accessible states such as `[aria-invalid="true"]`,
+`[aria-disabled="true"]`, `[aria-busy="true"]`, `[aria-current="page"]`, and
+required-field markers. See [Accessibility CSS](accessibility-css.md) for the
+markup contract.
+
+## List Utilities
+
+- `sf-list-reset` removes list markers and start padding for navigation or UI
+  lists.
+- `sf-list-disc` restores disc markers.
+- `sf-list-decimal` restores numbered markers.
+
+Do not reset content lists just to remove browser defaults. Keep markers when
+they carry meaning.
+
+## Modern CSS Baseline
+
+The base layer uses cascade layers, logical properties, low-specificity
+`:where()` selectors, OKLCH-aware `color-mix()`, `:focus-visible`, and
+`prefers-reduced-motion`. Utopia informs the fluid type, space, and grid
+tokens; Synced Flow owns the reset, accessibility helpers, and component
+defaults.