npm - @syncedco/flow - Versions diffs - 0.1.0 - Mend

@syncedco/flow 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (90) hide show

package/CODE_OF_CONDUCT.md +26 -0
package/CONTRIBUTING.md +54 -0
package/LICENSE +21 -0
package/README.md +334 -0
package/SECURITY.md +30 -0
package/SUPPORT.md +32 -0
package/TRADEMARKS.md +14 -0
package/base.css +100 -0
package/bin/synced-flow.mjs +4639 -0
package/components.css +1392 -0
package/defaults.css +26 -0
package/dist/config.d.ts +94 -0
package/dist/config.js +3 -0
package/dist/index.d.ts +45 -0
package/dist/index.js +67 -0
package/docs/accessibility-css.md +133 -0
package/docs/ai-usage.md +112 -0
package/docs/api-contract.md +81 -0
package/docs/base-styling.md +113 -0
package/docs/build-a-site-walkthrough.md +122 -0
package/docs/cli-reference.md +230 -0
package/docs/config-reference.md +81 -0
package/docs/css-optimisation.md +117 -0
package/docs/migration-from-tailwind.md +60 -0
package/docs/native-components.md +156 -0
package/docs/patterns.md +32 -0
package/docs/presets.md +60 -0
package/docs/quick-start.md +252 -0
package/docs/recipes.md +285 -0
package/docs/release-readiness.md +63 -0
package/docs/system-primitives.md +150 -0
package/docs/tailwind-comparison.md +66 -0
package/docs/tokens.md +79 -0
package/docs/website-patterns.md +114 -0
package/docs/why-synced-flow.md +99 -0
package/docs/wordpress.md +66 -0
package/examples/README.md +16 -0
package/examples/astro/package.json +19 -0
package/examples/astro/src/pages/index.astro +85 -0
package/examples/astro/src/styles/synced-flow.css +2 -0
package/examples/astro/src/styles/synced-flow.generated.css +206 -0
package/examples/astro/synced-flow.config.mjs +9 -0
package/examples/next/app/layout.tsx +14 -0
package/examples/next/app/page.tsx +92 -0
package/examples/next/app/synced-flow.css +2 -0
package/examples/next/app/synced-flow.generated.css +205 -0
package/examples/next/package.json +19 -0
package/examples/next/synced-flow.config.mjs +9 -0
package/examples/plain-html/index.html +384 -0
package/examples/plain-html/package.json +15 -0
package/examples/plain-html/synced-flow.config.mjs +9 -0
package/examples/plain-html/synced-flow.css +2 -0
package/examples/plain-html/synced-flow.generated.css +205 -0
package/examples/templates/README.md +22 -0
package/examples/templates/blog-index.html +41 -0
package/examples/templates/coming-soon.html +27 -0
package/examples/templates/portfolio-scroll.html +45 -0
package/examples/templates/saas-dashboard.html +171 -0
package/examples/templates/saas-landing.html +104 -0
package/examples/vite/index.html +2 -0
package/examples/vite/package.json +20 -0
package/examples/vite/src/main.jsx +27 -0
package/examples/vite/src/synced-flow.css +2 -0
package/examples/vite/src/synced-flow.generated.css +205 -0
package/examples/vite/synced-flow.config.mjs +9 -0
package/examples/wordpress/assets/css/synced-flow.css +641 -0
package/examples/wordpress/functions.php +13 -0
package/examples/wordpress/package.json +15 -0
package/examples/wordpress/parts/footer.html +12 -0
package/examples/wordpress/parts/header.html +10 -0
package/examples/wordpress/patterns/contact-cta.php +28 -0
package/examples/wordpress/patterns/feature-grid.php +38 -0
package/examples/wordpress/patterns/landing-hero.php +45 -0
package/examples/wordpress/synced-flow.config.mjs +11 -0
package/examples/wordpress/templates/front-page.html +11 -0
package/examples/wordpress/templates/index.html +27 -0
package/examples/wordpress/theme.json +19 -0
package/layout.css +365 -0
package/package.json +93 -0
package/reset.css +13 -0
package/skills/synced-flow/SKILL.md +151 -0
package/src/config.ts +98 -0
package/src/index.ts +75 -0
package/src/presets.d.mts +21 -0
package/src/presets.mjs +171 -0
package/src/tokens.mjs +138 -0
package/src/utility-tokens.mjs +47 -0
package/styles.css +2313 -0
package/tokens.css +198 -0
package/utilities.css +255 -0

package/docs/native-components.md ADDED Viewed

@@ -0,0 +1,156 @@
+# Native Components
+Synced Flow styles modern browser primitives instead of shipping JavaScript
+components. These patterns are progressive enhancements: use the native markup
+first, then add tiny project or example JavaScript only where state sync is
+needed.
+## Theme Control
+Use explicit theme selectors when a project owns theme state.
+```html
+<html data-sf-theme="light">
+<html data-sf-theme="dark">
+```
+The matching class selectors are also supported:
+```html
+<body class="sf-theme-light">
+<body class="sf-theme-dark">
+```
+Synced Flow sets `color-scheme` for native controls, forms, dialogs, and
+popover-backed UI. Projects can toggle the attribute however they like; the
+package does not ship a JavaScript theme switcher.
+## Dialog
+Use `<dialog>` for modal UI. Style the dialog with `sf-dialog` and structure it
+with the header/body/footer classes.
+```html
+<button class="sf-button" commandfor="settings-dialog" command="show-modal">
+  Open settings
+</button>
+<dialog class="sf-dialog" id="settings-dialog" aria-labelledby="settings-title">
+  <header class="sf-dialog__header">
+    <h2 id="settings-title">Settings</h2>
+    <button class="sf-button sf-button--ghost" commandfor="settings-dialog" command="close">Close</button>
+  </header>
+  <div class="sf-dialog__body">
+    <p class="sf-prose">Use native dialog behavior for focus and Escape handling where supported.</p>
+  </div>
+  <footer class="sf-dialog__footer">
+    <button class="sf-button" commandfor="settings-dialog" command="close">Done</button>
+  </footer>
+</dialog>
+```
+If the target browser does not support invoker commands yet, use a small project
+script to call `showModal()` and `close()`.
+## Popover, Tooltip, Drawer, Toast, And Banner
+Use the Popover API for non-modal overlays.
+```html
+<button class="sf-button" popovertarget="site-menu">Menu</button>
+<nav class="sf-drawer sf-drawer--right" id="site-menu" popover aria-label="Mobile">
+  <a class="sf-nav__link" href="/work">Work</a>
+  <a class="sf-nav__link" href="/contact">Contact</a>
+</nav>
+```
+Tooltips should keep the accessible description in markup. Native
+`interestfor` support is progressive, so pair the trigger with visible or
+described text when the content is important.
+```html
+<button class="sf-tooltip-trigger" interestfor="save-tip" aria-describedby="save-tip">
+  Save
+</button>
+<p class="sf-tooltip" id="save-tip" popover="hint">Saves your current draft.</p>
+```
+Use `sf-toast` and `sf-banner` for popover-backed announcements or feedback.
+## Disclosure And Accordions
+Use native `details` and `summary`. Give related details the same `name` value
+for an exclusive accordion in supporting browsers.
+```html
+<div class="sf-accordion">
+  <details name="pricing">
+    <summary>Can I customize the theme?</summary>
+    <p>Yes. Override Synced Flow tokens before adding custom CSS.</p>
+  </details>
+  <details name="pricing">
+    <summary>Does this need JavaScript?</summary>
+    <p>No for basic disclosure. The browser owns the open state.</p>
+  </details>
+</div>
+```
+## Tabs
+Tabs can be styled with `sf-tabs`, `sf-tab-list`, `sf-tab`, and `sf-tab-panel`.
+For fully accessible keyboard behavior and ARIA state sync, use a tiny
+project-level script. For simple CSS-only panels, radio inputs can control
+panels without package JavaScript.
+```html
+<section class="sf-tabs">
+  <div class="sf-tab-list" role="tablist" aria-label="Plans">
+    <button class="sf-tab" role="tab" aria-selected="true">Starter</button>
+    <button class="sf-tab" role="tab" aria-selected="false">Team</button>
+  </div>
+  <div class="sf-tab-panel" role="tabpanel">Starter plan content.</div>
+</section>
+```
+## Navigation
+Use `sf-nav--mobile` with a popover drawer for mobile navigation. Use
+`sf-breadcrumb` and `sf-pagination` for common content navigation.
+```html
+<nav class="sf-breadcrumb" aria-label="Breadcrumb">
+  <ol class="sf-breadcrumb">
+    <li><a href="/">Home</a></li>
+    <li><a href="/docs">Docs</a></li>
+    <li aria-current="page">Native components</li>
+  </ol>
+</nav>
+```
+## Scroll And Sticky
+Use CSS scroll snap and sticky positioning for full-page sections and sticky
+headers.
+```html
+<main class="sf-scroll-viewport" data-snap="mandatory">
+  <section class="sf-scroll-panel">
+    <div class="sf-container sf-stack">
+      <h1>First panel</h1>
+      <p class="sf-prose">Each panel snaps to the viewport.</p>
+    </div>
+  </section>
+  <section class="sf-scroll-panel">...</section>
+</main>
+```
+## Progressive Enhancement Notes
+- Popover API, invoker commands, interest invokers, and anchor positioning are
+  modern browser features. Use fallback-safe markup when content is critical.
+- Synced Flow provides styling and state hooks; it does not polyfill browser
+  APIs.
+- Prefer `dialog`, `popover`, `details`, scroll snap, `:popover-open`,
+  `::backdrop`, `:has()`, `color-scheme`, and anchor positioning before custom
+  JavaScript.

package/docs/patterns.md ADDED Viewed

@@ -0,0 +1,32 @@
+# Interaction Patterns
+Synced Flow patterns are copy-ready HTML/CSS-native building blocks for common
+website interactions. They are not JavaScript components.
+```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
+```
+## Pattern IDs
+| ID | Use |
+| --- | --- |
+| `mobile-nav-drawer` | Mobile burger, popover drawer, close button, and vertical nav list. |
+| `scroll-viewport-sections` | Sticky section nav plus full-height scroll snap panels. |
+| `scroll-viewport-with-spy` | Scroll snap panels with optional IntersectionObserver active-state notes. |
+| `native-dialog-react` | Native `<dialog>` markup plus React/Next fallback shape. |
+| `popover-drawer-layout` | Popover-backed drawer or filter panel with `sf-drawer--stack`. |
+Pattern JSON includes:
+- `classes`: public Synced Flow classes used by the pattern
+- `requiresJs` and `requiresJsNotes`: whether CSS/HTML alone is enough
+- `a11y`: accessibility requirements to preserve when editing
+- `gotchas`: browser or markup details that agents commonly miss
+- `markup`: framework-specific starter markup where useful
+Use patterns before hand-rolling interaction markup. Use recipes for full-page
+composition and patterns for the tricky native interaction details inside those
+pages.

package/docs/presets.md ADDED Viewed

@@ -0,0 +1,60 @@
+# Presets
+Synced Flow ships a small set of theme presets. They are intentionally small:
+fonts, semantic colours, layout defaults, and component token adjustments. The
+same public primitives should work across every preset.
+```js
+import { defineConfig } from '@syncedco/flow/config'
+import { themePresets } from '@syncedco/flow/presets'
+export default defineConfig({
+  scan: ['src'],
+  out: 'src/synced-flow.generated.css',
+  theme: themePresets.neutralSaas,
+})
+```
+## Available Presets
+| Preset | Use for |
+| --- | --- |
+| `synced` | Synced brand and warm marketing pages. Warm primary action, serif display, balanced component radius. |
+| `neutralSaas` | Calm SaaS, admin, and B2B apps. Neutral surfaces, blue action colour, slightly tighter controls. |
+| `editorial` | Content-heavy marketing and article-led sites. Narrower measure, round action buttons, more generous cards. |
+| `darkApp` | Dark dashboards, tools, and app surfaces. Dark semantic colours, stronger borders, compact controls. |
+CLI aliases use kebab case:
+```bash
+synced-flow init --theme synced
+synced-flow init --theme neutral-saas
+synced-flow init --theme editorial
+synced-flow init --theme dark-app
+```
+## What Presets Override
+Presets use the same config surface available to consuming projects:
+- `fonts` for `--sf-font-*`.
+- `colours` and `darkColours` for semantic `--sf-colour-*` roles.
+- `layout` for container width, gutter, and grid defaults.
+- `components` for button, card, and input sizing/radius.
+Keep project-specific brand details in the consuming app config. Presets should
+stay broad enough to start a category of project without becoming full themes.
+## Preset Confidence Rule
+Every preset should support the same recipe snippets:
+- marketing homepage
+- SaaS product page
+- documentation page
+- contact form
+- app shell
+- pricing and FAQ
+If a preset needs page-specific CSS to make those recipes usable, improve the
+preset tokens before adding new classes.

package/docs/quick-start.md ADDED Viewed

@@ -0,0 +1,252 @@
+# Quick Start
+Synced Flow is a small fluid CSS system for projects that want strong design
+tokens, generated utility CSS, and no default dependency on viewport breakpoints.
+## Install
+```bash
+pnpm add @syncedco/flow
+pnpm exec synced-flow init --theme synced
+```
+For the GitHub repo before registry publishing:
+```bash
+pnpm add git+https://github.com/SyncedCo/synced-flow.git
+pnpm exec synced-flow init
+```
+## Shape The Theme First
+Before building pages, answer a small theme brief. This keeps brand decisions in
+tokens instead of scattered page CSS.
+- Radius: sharp, slightly rounded, or soft/curved?
+- Font family: system, geometric sans, editorial serif, or brand font?
+- Primary colour: main action and focus colour.
+- Secondary/accent colour: supporting highlights.
+- Surface style: flat, raised cards, or subtle panels?
+- Density: compact app UI or more spacious marketing pages?
+With an AI assistant, ask it to use the Synced Flow skill and turn those
+answers into `synced-flow.config.mjs` theme tokens.
+Example prompt:
+```text
+Use the Synced Flow skill. Create a website theme with slightly rounded
+controls, Inter for UI, Fraunces for display headings, orange as the primary
+colour, cyan as the accent, light raised cards, and spacious marketing sections.
+Return the Synced Flow theme config only.
+```
+Then place the result in `synced-flow.config.mjs`:
+```js
+theme: {
+  fonts: {
+    sans: 'Inter, ui-sans-serif, system-ui, sans-serif',
+    display: 'Fraunces, Georgia, serif',
+  },
+  colours: {
+    primary: 'oklch(68% 0.18 44)',
+    primaryForeground: 'oklch(100% 0 0)',
+    accent: 'oklch(70% 0.12 205)',
+    ring: 'oklch(68% 0.18 44)',
+  },
+  components: {
+    button: { radius: '0.5rem' },
+    card: { radius: '0.75rem' },
+    input: { radius: '0.5rem' },
+  },
+}
+```
+## Import
+`init` creates a CSS entry file such as `src/synced-flow.css` or
+`app/synced-flow.css`.
+Import that file once from your app entry, root layout, or main CSS file.
+```ts
+import './synced-flow.css'
+```
+Choose one core import strategy. Most projects use the full package stylesheet:
+```css
+@import "@syncedco/flow/styles.css";
+@import "@syncedco/flow/defaults.css";
+@import "./synced-flow.generated.css";
+```
+`styles.css` already includes tokens, reset, base, layout, components, and
+static utilities. Do not also import those modular files alongside `styles.css`.
+For tighter 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";
+@import "./synced-flow.generated.css";
+```
+`defaults.css` is optional. It removes raw link underlines and list markers for
+common site/UI surfaces. Leave it out, or run `synced-flow init --no-defaults`, when a
+project should keep content-style browser defaults.
+Keep `utilities.css` out unless the project uses static helpers such as
+`sf-text-*`, `sf-prose`, `sr-only`, `not-sr-only`, `sf-skip-link`,
+`sf-focus-ring`, `sf-touch-target`, `sf-list-reset`, `sf-link`, or
+`sf-full-bleed`. The generated CSS file already emits source-scanned utility
+classes.
+For the supported starter surface, see [System primitives](system-primitives.md).
+It lists the tokens, layout classes, component classes, and utility helpers that
+can build a basic website before project-specific CSS is needed.
+For copy-ready website sections, see [Website patterns](website-patterns.md).
+For native dialog, popover, disclosure, drawer, tooltip, tabs, and scroll
+patterns, see [Native Components](native-components.md).
+For accessible state styling and markup hooks, see
+[Accessibility CSS](accessibility-css.md).
+For the stable public surface, see [CSS API Contract](api-contract.md).
+For a full project flow, see [Build a site walkthrough](build-a-site-walkthrough.md).
+## Base Defaults
+Synced Flow uses a conservative base: links remain visibly underlined, lists
+keep their markers, focus styles are visible, and motion preferences are
+respected. Add `@syncedco/flow/defaults.css` or run `synced-flow add defaults` when a
+site should use app-style defaults globally.
+## Build
+```bash
+pnpm flow:build
+pnpm flow:check
+pnpm flow:lint
+pnpm flow:doctor
+```
+In this repository, `pnpm check` also runs package guardrails for dependency
+count, gzip budgets, generated CSS shape, and raw-pixel usage.
+## Theme Tokens
+Override reusable project tokens in `synced-flow.config.mjs`.
+```js
+export default defineConfig({
+  scan: ['src', 'components'],
+  out: 'src/synced-flow.generated.css',
+  theme: {
+    fonts: {
+      sans: 'Inter, ui-sans-serif, system-ui, sans-serif',
+      display: 'Fraunces, Georgia, serif',
+    },
+    colours: {
+      primary: 'oklch(68% 0.18 44)',
+      primaryForeground: 'oklch(100% 0 0)',
+    },
+  },
+})
+```
+Use the CSS entry file for one-off local overrides.
+```css
+@import "@syncedco/flow/styles.css";
+@import "./synced-flow.generated.css";
+:root {
+  --sf-font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+  --sf-colour-primary: oklch(68% 0.18 44);
+}
+```
+## Config
+```js
+import { defineConfig } from '@syncedco/flow/config'
+export default defineConfig({
+  scan: ['src', 'components'],
+  out: 'src/synced-flow.generated.css',
+  responsiveVariants: false,
+  safelist: [],
+})
+```
+## Presets
+```bash
+pnpm exec synced-flow init --preset next
+pnpm exec synced-flow init --preset vite
+pnpm exec synced-flow init --preset astro
+pnpm exec synced-flow init --preset wordpress
+pnpm exec synced-flow init --preset plain
+pnpm exec synced-flow init --theme neutral-saas
+```
+Use `--responsive-variants` only for migration projects that still contain
+classes like `sm:` or `lg:`.
+## Scanner Limits
+Synced Flow scans source files as text and generates CSS for complete class
+tokens. Keep class names complete in source files.
+```tsx
+// Good
+const variants = {
+  primary: 'bg-primary text-primary-foreground',
+  quiet: 'bg-surface text-heading',
+}
+// Avoid
+const colour = 'primary'
+const className = `bg-${colour}`
+```
+For dynamic cases that cannot be avoided, use `safelist`.
+## WordPress
+The WordPress preset is designed for themes and plugins that enqueue plain CSS.
+It scans PHP and template files, enables `includeCore`, and writes one CSS file:
+```bash
+pnpm exec synced-flow init --preset wordpress
+pnpm flow:build
+```
+Enqueue the generated file from the theme or plugin:
+```php
+wp_enqueue_style(
+  'synced-flow',
+  get_theme_file_uri('assets/css/synced-flow.css'),
+  [],
+  wp_get_theme()->get('Version')
+);
+```
+## AI-Friendly Discovery
+```bash
+pnpm exec synced-flow tokens
+pnpm exec synced-flow tokens --json
+pnpm exec synced-flow catalog --json
+pnpm exec synced-flow suggest "service site with pricing and faq"
+```
+Use this before generating UI so class names, token names, and presets stay
+inside the supported surface area.