@syncedco/flow 0.1.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,26 @@
+# Code Of Conduct
+
+Synced Flow aims to be a practical, respectful open-source project.
+
+## Expected Behaviour
+
+- Be considerate and constructive.
+- Keep feedback focused on the work.
+- Assume good intent, and ask for clarification when something is unclear.
+- Respect maintainers' time and project scope.
+- Welcome people with different levels of CSS, design-system, WordPress, and
+  frontend experience.
+
+## Unacceptable Behaviour
+
+- Harassment, threats, or personal attacks.
+- Discriminatory language or behaviour.
+- Repeated off-topic, hostile, or bad-faith comments.
+- Publishing private information without permission.
+- Pressuring maintainers for unpaid commercial support.
+
+## Reporting
+
+Report conduct concerns to SyncedCo through [syncedco.com](https://syncedco.com).
+Maintainers may remove comments, close issues, or block contributors when needed
+to keep the project healthy.

package/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+Thanks for considering a contribution to Synced Flow.
+
+Synced Flow is an open-source fluid CSS design system maintained by SyncedCo.
+The core project includes the CSS library, CLI, WordPress preset, examples, and
+documentation.
+
+## Local Setup
+
+```bash
+pnpm install
+pnpm test
+```
+
+Useful commands:
+
+```bash
+pnpm build
+pnpm check
+pnpm pack --dry-run
+```
+
+## Contribution Guidelines
+
+- Keep changes focused and easy to review.
+- Prefer modern CSS features already used by the project: cascade layers,
+  custom properties, logical properties, `clamp()`, OKLCH colour, and
+  container-aware layout.
+- Keep new APIs small and documented.
+- Add or update tests for CLI, package, or generated CSS behaviour.
+- Use complete class names in docs and examples so the scanner can find them.
+- Avoid positioning Synced Flow as a Tailwind copy or one-for-one replacement;
+  Tailwind references should only support migration from existing projects.
+- Use British English in documentation.
+
+## Before Opening A Pull Request
+
+Run:
+
+```bash
+pnpm check
+pnpm test
+pnpm pack --dry-run
+```
+
+For documentation-only changes, `pnpm check` is usually enough unless package
+metadata or generated files changed.
+
+## Commercial Work
+
+Commercial services, premium templates, hosted tools, and paid starter kits are
+optional work around the open-source core. They are not part of this package
+unless explicitly released here.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SyncedCo Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,334 @@
+# Synced Flow
+
+AI-native fluid CSS design system for brand-consistent websites, agency builds,
+and modern frontend projects.
+
+Synced Flow gives developers and AI coding agents a shared styling contract:
+fluid tokens, layout primitives, accessible components, website recipes, and
+source-scanned utility CSS.
+
+Use it when you want AI-assisted build speed without breakpoint soup, one-off
+brand drift, or generated class chaos.
+
+- fluid by default: Utopia-style type and spacing with modern `clamp()` scales
+- token-led: primitive, semantic, and component tokens using CSS custom
+  properties and OKLCH colour
+- agent-readable: `catalog --json`, `suggest`, `recipe`, `pattern`, `lint`,
+  `doctor`, and project-local AI guidance
+- agency-ready: presets for WordPress, Next, Astro, Vite, and plain HTML
+- accessible defaults: visible focus states, skip links, reduced-motion
+  safeguards, and state styling
+- lean CSS loading: modular layers plus generated utilities scanned from real
+  project usage
+- layout primitives: container, section, stack, cluster, grid, sidebar,
+  switcher, frame, cover, hero, and flow
+- component primitives: buttons, cards, surfaces, navigation, forms, alerts,
+  badges, avatars, charts, and section headers
+- website patterns: logo clouds, feature blocks, stats, testimonials, pricing,
+  FAQ, CTA, and footer helpers
+- native component styling: dialog, popover, drawer, tooltip, disclosure, tabs,
+  breadcrumbs, pagination, scroll snap, and sticky patterns
+- AI-friendly CLI discovery: `catalog --json`, `suggest`, `lint`, `watch`, and
+  `theme init --from` for turning a site brief into reusable theme tokens
+- project-level AI agent setup: `agents install`, `agents status`, and `skill`
+  make the packaged Synced Flow skill visible to common coding agents
+- accessibility and base helpers: `sr-only`, `not-sr-only`, skip links, focus
+  rings, touch targets, link helpers, and list helpers
+- accessibility state styling for invalid, required, disabled, busy, current,
+  expanded, pressed, selected, target, and forced-colors states
+- modular CSS layer exports when a project wants a smaller imported surface
+- modern CSS best practices: cascade layers, custom properties, logical
+  properties, `clamp()`, OKLCH colour, container-aware primitives, and
+  reduced-motion safeguards
+
+## Links
+
+- GitHub: [github.com/SyncedCo/synced-flow](https://github.com/SyncedCo/synced-flow)
+- Website: [syncedco.com](https://syncedco.com)
+- Issues: [github.com/SyncedCo/synced-flow/issues](https://github.com/SyncedCo/synced-flow/issues)
+- Support: [SUPPORT.md](SUPPORT.md)
+
+## Open Source
+
+Synced Flow core is released under the [MIT licence](LICENSE). The open-source
+core includes the CSS library, CLI, WordPress preset, modern frontend examples,
+documentation, and recipes.
+
+Useful project files:
+
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+- [Support](SUPPORT.md)
+- [Trademark and brand use](TRADEMARKS.md)
+
+The MIT licence covers the software. It does not grant rights to use Synced,
+SyncedCo, or Synced Flow branding in a way that implies official endorsement.
+
+## Install
+
+```bash
+pnpm add @syncedco/flow
+pnpm exec synced-flow init --preset next --theme synced --agents
+```
+
+`--agents` adds project-level AI guidance so Cursor, Codex-style agents, Claude,
+Copilot, Windsurf, Gemini, and Aider can discover the Synced Flow skill and
+recommended CLI checks from the consuming project.
+
+Until the package is published to a registry, install it from the GitHub repo:
+
+```bash
+pnpm add git+https://github.com/SyncedCo/synced-flow.git
+```
+
+## Import
+
+Most projects should choose one core import strategy.
+
+Use the full stylesheet when simplicity matters:
+
+```css
+@import "@syncedco/flow/styles.css";
+@import "@syncedco/flow/defaults.css";
+```
+
+`styles.css` already includes the tokens, reset, base, layout, components, and
+static utilities layers. Do not also import those modular layer files alongside
+`styles.css`.
+
+`defaults.css` is optional. It applies common site/UI defaults such as removing raw
+link underlines and list markers. Leave it out for content-heavy pages that
+should keep browser affordances by default.
+
+For tighter CSS loading, skip `styles.css` and import only the layers the
+project uses:
+
+```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";
+```
+
+## CSS Size And Loading
+
+Synced Flow is designed to avoid shipping a large universal utility stylesheet.
+It uses modern CSS techniques and keeps CSS loading compact in three ways:
+
+- the CLI scans source files and generates utility CSS only for discovered class
+  tokens
+- CSS layers are exported separately, so projects can import only tokens, reset,
+  base, defaults, layout, components, or static utilities as needed
+- generated animation keyframes are emitted only when scanned animation classes
+  need them
+
+The core CSS is built around current browser capabilities rather than legacy
+breakpoint-heavy patterns: fluid `clamp()` scales, CSS custom properties,
+logical sizing and spacing, cascade layers, OKLCH colour tokens,
+container-aware layout primitives, and `prefers-reduced-motion` handling.
+
+Current built CSS sizes from `pnpm build` on 2026-05-28:
+
+| File | Raw | Gzip | Purpose |
+| --- | ---: | ---: | --- |
+| `styles.css` | 59.1 KB | 10.5 KB | Full core stylesheet for simple setup. |
+| `tokens.css` | 9.5 KB | 2.2 KB | Design tokens only. |
+| `reset.css` | 0.7 KB | 0.4 KB | Reset layer only. |
+| `base.css` | 3.4 KB | 1.2 KB | Base element styles. |
+| `defaults.css` | 0.5 KB | 0.3 KB | Optional site/UI defaults for links, lists, and native controls. |
+| `layout.css` | 7.5 KB | 1.9 KB | Fluid layout, app shell, scroll, sticky, media, and split primitives. |
+| `components.css` | 31.3 KB | 5.0 KB | Button, icon, avatar, chart, card, surface, nav, form, alert, native component, website pattern, accessibility state, and input primitives. |
+| `utilities.css` | 7.5 KB | 1.9 KB | Static `sf-*` content, positioning, motion, and helper utilities. |
+
+CSS is not automatically tree-shaken like JavaScript in every environment. The
+Synced Flow approach is explicit and predictable: import the core layers you
+need, then run `synced-flow build` so project utilities are generated from real
+usage.
+
+For WordPress themes and plugins, `synced-flow init --preset wordpress` scans
+PHP/template files and writes one enqueue-ready CSS file at
+`assets/css/synced-flow.css`.
+
+See [CSS optimisation](docs/css-optimisation.md) for the full measurements,
+developer notes, and marketing-safe claims.
+
+## Base Styling Decisions
+
+Synced Flow keeps the browser affordances people rely on:
+
+- links stay visibly underlined by default
+- `ul` and `ol` keep their markers by default
+- focus states are visible through `:focus-visible`
+- reduced-motion preferences are respected
+
+Use opt-in helpers when UI needs a different treatment: `sf-link-plain` for
+navigation links, `sf-list-reset` for menu lists, `sr-only` for assistive text,
+`sf-skip-link` for skip navigation, and `sf-touch-target` for compact controls.
+For site/UI projects, include `@syncedco/flow/defaults.css` or run
+`synced-flow add defaults` to apply those common UI defaults globally.
+
+See [Base styling decisions](docs/base-styling.md).
+
+## Icons
+
+Synced Flow supports icons without shipping an icon set. Use `sf-icon` on
+inline SVGs or external libraries such as Lucide, Heroicons, or Bootstrap Icons;
+icons inherit `currentColor` and size from fluid system tokens.
+
+```tsx
+import { Settings } from "lucide-react"
+
+<button className="sf-button">
+  <Settings className="sf-icon" aria-hidden="true" />
+  Settings
+</button>
+```
+
+## Configure
+
+`synced-flow init` creates `synced-flow.config.mjs`, a CSS entry file, a
+generated CSS placeholder, and `flow:build` / `flow:check` / `flow:lint` /
+`flow:watch` package scripts.
+
+To add AI agent guidance to an existing project:
+
+```bash
+pnpm exec synced-flow agents install
+pnpm exec synced-flow agents status
+pnpm exec synced-flow skill
+```
+
+Use `--target all` to also add tool-specific project files for Cursor, Claude,
+Copilot, Windsurf, Gemini, and Aider where those tools support project-local
+instructions or skills.
+
+Start by shaping the theme: radius style, font family, primary colour, accent
+colour, surface treatment, and density. With AI, ask it to use the Synced Flow
+skill and convert that brief into `synced-flow.config.mjs` theme tokens before
+building pages.
+
+You can also create the config by hand:
+
+```js
+import { defineConfig } from '@syncedco/flow/config'
+import { themePresets } from '@syncedco/flow/presets'
+
+export default defineConfig({
+  scan: ['app', 'components', 'lib'],
+  out: 'app/synced-flow.generated.css',
+  responsiveVariants: false,
+  theme: themePresets.synced,
+  safelist: ['hidden', 'flex'],
+})
+```
+
+Import the generated file after the core stylesheet:
+
+```ts
+import '@syncedco/flow/styles.css'
+import './synced-flow.generated.css'
+```
+
+Add package scripts:
+
+```json
+{
+  "scripts": {
+    "flow:build": "synced-flow build",
+    "flow:check": "synced-flow build --check",
+    "flow:lint": "synced-flow lint",
+    "flow:watch": "synced-flow watch",
+    "flow:doctor": "synced-flow doctor"
+  }
+}
+```
+
+Run setup checks:
+
+```bash
+pnpm flow:doctor
+```
+
+Discover the supported starter surface:
+
+```bash
+pnpm exec synced-flow tokens
+pnpm exec synced-flow tokens --json
+pnpm exec synced-flow catalog --json
+pnpm exec synced-flow suggest "full page scroll portfolio"
+pnpm exec synced-flow recipe portfolio-scroll --markup
+pnpm exec synced-flow recipe portfolio-scroll --framework next --markup
+pnpm exec synced-flow theme init --from brief.md
+pnpm exec synced-flow theme init --from brief.md --preset-base neutral-saas
+```
+
+## Use
+
+```html
+<section class="sf-section">
+  <div class="sf-container sf-stack" style="--sf-stack-space: var(--sf-space-l)">
+    <span class="sf-badge">Fluid by default</span>
+    <h1 class="sf-text-display">A styling system that adapts without layout breakpoints.</h1>
+    <p class="sf-text-lead sf-prose">Use shared tokens and layout primitives before project-specific styling.</p>
+    <a class="sf-button" href="/contact">Start a project</a>
+  </div>
+</section>
+```
+
+The CLI also accepts flags for projects that do not want a config file:
+
+```bash
+synced-flow build --scan app --scan components --out app/synced-flow.generated.css
+```
+
+Use `--include-core` only when you want the generated CSS file to contain the
+reset, base, layout, and component layers instead of importing
+`@syncedco/flow/styles.css` separately.
+
+For WordPress themes or plugins, use the WordPress preset. It scans PHP and
+template files and writes one CSS file that can be enqueued directly:
+
+```bash
+pnpm exec synced-flow init --preset wordpress
+pnpm flow:build
+```
+
+New projects should keep `responsiveVariants` off. Turn it on only when migrating
+an existing codebase that still contains compatibility classes such as `sm:` or
+`lg:`.
+
+## Docs
+
+- [Why Synced Flow?](docs/why-synced-flow.md)
+- [Quick start](docs/quick-start.md)
+- [Build a site walkthrough](docs/build-a-site-walkthrough.md)
+- [AI usage guide](docs/ai-usage.md)
+- [Base styling decisions](docs/base-styling.md)
+- [Accessibility CSS](docs/accessibility-css.md)
+- [System primitives](docs/system-primitives.md)
+- [CSS API contract](docs/api-contract.md)
+- [Native components](docs/native-components.md)
+- [Website patterns](docs/website-patterns.md)
+- [CLI reference](docs/cli-reference.md)
+- [Config reference](docs/config-reference.md)
+- [CSS optimisation](docs/css-optimisation.md)
+- [Presets](docs/presets.md)
+- [Recipes](docs/recipes.md)
+- [Release readiness](docs/release-readiness.md)
+- [WordPress](docs/wordpress.md)
+- [Synced Flow skill](skills/synced-flow/SKILL.md)
+- [Tokens guide](docs/tokens.md)
+- [Tailwind comparison](docs/tailwind-comparison.md)
+- [Migration from Tailwind](docs/migration-from-tailwind.md)
+
+## Scripts
+
+```bash
+pnpm build
+pnpm check
+pnpm type-check
+```

package/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Supported Versions
+
+Synced Flow is currently pre-1.0. Security fixes target the latest published
+version and the current `main` branch.
+
+## Reporting A Vulnerability
+
+Please do not open a public GitHub issue for suspected vulnerabilities.
+
+Report security concerns to SyncedCo through [syncedco.com](https://syncedco.com)
+and include:
+
+- affected package version or commit
+- affected command, file, or integration
+- reproduction steps
+- expected and actual impact
+- any relevant logs or generated CSS output
+
+We will review the report, confirm whether the issue is valid, and coordinate a
+fix before public disclosure where appropriate.
+
+## Scope
+
+Security reports may include issues in the CLI, generated CSS output, package
+distribution, examples, or WordPress integration guidance.
+
+General support questions, styling issues, and feature requests should use
+[GitHub issues](https://github.com/SyncedCo/synced-flow/issues).

package/SUPPORT.md

@@ -0,0 +1,32 @@
+# Support
+
+Synced Flow is maintained by SyncedCo.
+
+- Website: [syncedco.com](https://syncedco.com)
+- GitHub: [github.com/SyncedCo/synced-flow](https://github.com/SyncedCo/synced-flow)
+- Issues: [github.com/SyncedCo/synced-flow/issues](https://github.com/SyncedCo/synced-flow/issues)
+- Security: [SECURITY.md](SECURITY.md)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Community Support
+
+Use GitHub issues for reproducible bugs, documentation problems, CLI issues,
+and focused feature requests for the open-source core.
+
+Before opening an issue, please include:
+
+- the package version
+- the framework or environment
+- the relevant `synced-flow.config.mjs`
+- the command that failed
+- the expected and actual behaviour
+
+## Commercial And Team Support
+
+For paid implementation, design-system audits, WordPress/theme integration,
+training, workshops, or team support, contact SyncedCo through
+[syncedco.com](https://syncedco.com).
+
+Commercial services are optional support around the open-source core. Premium
+templates, hosted tools, and paid starter kits are not included in this package
+unless explicitly released separately.

package/TRADEMARKS.md

@@ -0,0 +1,14 @@
+# Trademark And Brand Use
+
+The MIT licence covers the Synced Flow software. It does not grant trademark,
+brand, logo, or endorsement rights.
+
+Names such as Synced, SyncedCo, and Synced Flow may be used to truthfully refer
+to this project, compatibility, forks, or integrations.
+
+Do not use Synced, SyncedCo, or Synced Flow names, logos, or branding in a way
+that suggests official sponsorship, endorsement, partnership, or ownership
+unless SyncedCo has given written permission.
+
+Forks and derived projects should use a distinct name if they are distributed as
+their own product.

package/base.css

@@ -0,0 +1,100 @@
+/* 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 base {
+  html {
+    background: var(--sf-colour-background);
+    color: var(--sf-colour-foreground);
+    scroll-behavior: smooth;
+  }
+
+  body {
+    background: var(--sf-colour-background);
+    color: var(--sf-colour-foreground);
+    font-family: var(--sf-font-sans);
+    font-size: var(--sf-type-body);
+    line-height: var(--sf-line-height-body);
+    -webkit-font-smoothing: antialiased;
+    text-rendering: optimizeLegibility;
+  }
+
+  :where(h1, h2, h3, h4, h5, h6) {
+    color: inherit;
+    font-family: var(--sf-font-display);
+    font-weight: 700;
+    line-height: var(--sf-line-height-tight);
+    text-wrap: balance;
+  }
+
+  :where(h1) { font-size: var(--sf-type-h1); }
+  :where(h2) { font-size: var(--sf-type-h2); }
+  :where(h3) { font-size: var(--sf-type-h3); }
+  :where(h4) { font-size: var(--sf-type-h4); }
+  :where(h5) { font-size: var(--sf-type-h5); }
+  :where(h6) { font-size: var(--sf-type-h6); }
+  :where(p, li, dd, figcaption) { text-wrap: pretty; }
+  :where(a) {
+    color: var(--sf-colour-link);
+    text-decoration-color: color-mix(in oklch, currentColor 55%, transparent);
+    text-decoration-skip-ink: auto;
+    text-decoration-thickness: .08em;
+    text-underline-offset: .18em;
+  }
+  :where(a:hover) { color: var(--sf-colour-link-hover); }
+  :where(strong, b) { font-weight: 800; }
+  :where(small) { font-size: var(--sf-step--1); }
+  :where(code, kbd, samp, pre) { font-family: var(--sf-font-mono); }
+  :where(:not(pre) > code, kbd) {
+    background: var(--sf-colour-surface-alt);
+    border: 1px solid var(--sf-colour-border);
+    border-radius: var(--sf-radius-sm);
+    font-size: .9em;
+    padding: .1em .35em;
+  }
+  :where(pre) {
+    background: var(--sf-colour-surface-inset);
+    border: 1px solid var(--sf-colour-border);
+    border-radius: var(--sf-radius-panel);
+    overflow-x: auto;
+    padding: var(--sf-space-s);
+  }
+  :where(hr) {
+    border: 0;
+    border-block-start: 1px solid var(--sf-colour-border);
+    margin-block: var(--sf-space-l);
+  }
+  :where(blockquote) {
+    border-inline-start: 0.25rem solid var(--sf-colour-primary);
+    color: var(--sf-colour-muted);
+    padding-inline-start: var(--sf-space-s);
+  }
+  :where(label) { cursor: pointer; }
+  :where(input, textarea, select) { color: inherit; }
+  :where(textarea) { resize: vertical; }
+  :where(button:not(:disabled), [role="button"]:not(:disabled), a[href]) { cursor: pointer; }
+  :where(button:disabled, input:disabled, textarea:disabled, select:disabled, [aria-disabled="true"]) { cursor: not-allowed; }
+  :where(:focus-visible) { outline: 0.125rem solid var(--sf-colour-ring); outline-offset: .2rem; }
+  :where(:target) { scroll-margin-block: var(--sf-space-l); }
+  ::selection { background: color-mix(in oklch, var(--sf-colour-primary) 28%, transparent); }
+
+  @media (prefers-reduced-motion: reduce) {
+    html { scroll-behavior: auto; }
+    *, *::before, *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      scroll-behavior: auto !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(:focus-visible) {
+      outline: 2px solid Highlight;
+      outline-offset: .2rem;
+    }
+
+    ::selection {
+      background: Highlight;
+      color: HighlightText;
+    }
+  }
+}