@syncedco/flow 0.1.0 → 0.1.2

package/README.md

@@ -44,6 +44,7 @@ brand drift, or generated class chaos.
 ## Links
 
 - GitHub: [github.com/SyncedCo/synced-flow](https://github.com/SyncedCo/synced-flow)
+- Docs: [docs.syncedflow.dev](https://docs.syncedflow.dev)
 - 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)

package/bin/synced-flow.mjs

@@ -2909,7 +2909,7 @@ function selectorFor(token, variants) {
 function colourValue(name) {
   const [raw, opacity] = name.split('/')
   const paletteMatch = raw.match(/^([a-z]+)-(\d+)$/)
-  const base = semanticColours[raw] ?? (paletteMatch ? palette[paletteMatch[1]]?.[paletteMatch[2]] : null)
+  const base = semanticColours[raw] ?? configuredThemeColourValue(raw) ?? (paletteMatch ? palette[paletteMatch[1]]?.[paletteMatch[2]] : null)
   if (!base) return null
   if (!opacity) return base
   const amount = Number(opacity)
@@ -2918,6 +2918,16 @@ function colourValue(name) {
   return `color-mix(in oklch, ${base} ${amount}%, transparent)`
 }
 
+function configuredThemeColourValue(name) {
+  const token = cssTokenName(name)
+  const colourNames = [
+    ...Object.keys(config.theme?.colours ?? {}),
+    ...Object.keys(config.theme?.darkColours ?? {}),
+  ].map(cssTokenName)
+
+  return colourNames.includes(token) ? `var(--color-${token}, var(--sf-colour-${token}))` : null
+}
+
 function declarationsFor(base) {
   if (base.startsWith('sf-')) return []
 
@@ -3562,7 +3572,7 @@ function buildThemeCss(theme) {
     sections.push(`  :where(.sf-theme-dark, [data-sf-theme="dark"]) {\n${dark.join('\n')}\n  }`)
   }
 
-  return `@layer tokens {\n${sections.join('\n\n')}\n}`
+  return sections.join('\n\n')
 }
 
 function buildTokensCss() {
@@ -3604,8 +3614,7 @@ function buildTokensCss() {
 
   const colours = fluidConfig.colours
 
-  return `@layer tokens {
-  :root {
+  return `:root {
     color-scheme: light;
     --font-sans: var(--sf-font-sans, ui-sans-serif, system-ui, sans-serif);
     --font-display: var(--sf-font-display, ui-serif, Georgia, serif);
@@ -3725,8 +3734,7 @@ ${pairs.join('\n')}
     --ease-standard: cubic-bezier(.2, 0, 0, 1);
     --icon-size: 1em;
     --icon-stroke: 2;
-  }
-}`
+  }`
 }
 
 function buildBaseCss() {

package/docs/api-contract.md

@@ -11,7 +11,7 @@ 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` |
+| Tokens | Unlayered `--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` |
@@ -46,6 +46,17 @@ These can change more freely.
   They are useful for migration output, but `--sf-*` tokens are the preferred
   long-term API.
 
+## Theme Cascade Policy
+
+Design tokens are intentionally emitted outside CSS layers. Synced Flow uses
+layers for reset, base, layout, components, and utilities, but foundational
+theme variables need the normal cascade so values from `synced-flow.config.mjs`
+are not weaker than unlayered project CSS.
+
+Put reusable brand decisions in `theme.colours`, `theme.darkColours`,
+`theme.radii`, `theme.layout`, and `theme.components`. Theme switcher CSS should
+only style the toggle/control UI; it should not redefine `--sf-*` colour tokens.
+
 ## Unit Policy
 
 Design decisions should use `rem`, fluid `clamp()` tokens, logical properties,

package/docs/cli-reference.md

@@ -78,6 +78,10 @@ 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.
 
+Configured theme tokens are emitted outside CSS layers so they are not weaker
+than unlayered project CSS. Use `theme.darkColours` for dark theme values rather
+than maintaining duplicate colour overrides in a theme switcher stylesheet.
+
 ## watch
 
 Run `build`, then rebuild when configured scan files change.

package/docs/quick-start.md

@@ -154,8 +154,14 @@ export default defineConfig({
     },
     colours: {
       primary: 'oklch(68% 0.18 44)',
+      secondary: 'oklch(62% 0.12 205)',
+      tertiary: 'oklch(64% 0.14 185)',
       primaryForeground: 'oklch(100% 0 0)',
     },
+    darkColours: {
+      primary: 'oklch(76% 0.14 44)',
+      tertiary: 'oklch(82% 0.12 205)',
+    },
   },
 })
 ```
@@ -172,6 +178,10 @@ Use the CSS entry file for one-off local overrides.
 }
 ```
 
+Synced Flow emits theme tokens outside CSS layers so config values are the site
+theme source of truth. Keep theme switcher styles focused on the toggle UI; do
+not mirror colour tokens into a separate `theme-switcher.css` file.
+
 ## Config
 
 ```js

package/docs/release-readiness.md

@@ -61,3 +61,21 @@ 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.
+
+## npm Trusted Publishing
+
+Publishing is handled by `.github/workflows/npm-publish.yml` when a `v*` tag is
+pushed. The workflow checks that the tag matches `package.json`, installs with
+pnpm, runs tests, verifies package contents, and publishes with npm trusted
+publishing.
+
+Configure npm package trusted publishing for `@syncedco/flow` with:
+
+- Provider: GitHub Actions
+- Organization or user: `SyncedCo`
+- Repository: `synced-flow`
+- Workflow filename: `npm-publish.yml`
+- Allowed action: `npm publish`
+
+After this is verified, prefer npm's package setting to require two-factor
+authentication and disallow token publishing.

package/docs/tokens.md

@@ -28,6 +28,11 @@ Semantic tokens describe intent.
 --sf-colour-success-soft: oklch(62% 0.13 150 / 0.12);
 ```
 
+Tokens are emitted outside CSS layers so configured themes can act as the
+source of truth for brand colours, radius, layout, and component decisions.
+Use `theme.darkColours` for dark-mode values instead of maintaining a separate
+CSS file that redefines `--sf-*` variables.
+
 Use semantic utilities in projects:
 
 ```html
@@ -77,3 +82,9 @@ The generated core includes enough semantic variables for common website UI:
   `--sf-radius-control`, `--sf-radius-panel`, `--sf-shadow-*`
 
 For class-level usage, see [System primitives](system-primitives.md).
+
+Custom semantic colour names from `theme.colours`, such as `secondary` or
+`tertiary`, are emitted as CSS variables and can be consumed directly with
+`var(--sf-colour-tertiary)`. Generated colour utilities are available when the
+class token is present in scanned source, for example `text-tertiary` or
+`bg-tertiary`.

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@syncedco/flow",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AI-native fluid CSS design system for brand-consistent websites and agency builds.",
   "type": "module",
+  "packageManager": "pnpm@11.2.2",
   "license": "MIT",
   "keywords": [
     "css",
@@ -21,7 +22,7 @@
     "type": "git",
     "url": "git+https://github.com/SyncedCo/synced-flow.git"
   },
-  "homepage": "https://syncedco.com",
+  "homepage": "https://docs.syncedflow.dev",
   "bugs": {
     "url": "https://github.com/SyncedCo/synced-flow/issues"
   },

package/styles.css

@@ -1,7 +1,6 @@
 /* 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 tokens {
-  :root {
+:root {
     color-scheme: light;
 
     --sf-font-sans: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
@@ -195,7 +194,6 @@
     --sf-colour-link: var(--sf-colour-orange-500);
     --sf-colour-link-hover: oklch(80% 0.14 50);
   }
-}
 @layer reset {
   *, *::before, *::after { box-sizing: border-box; }
   *:where(:not(dialog)) { margin: 0; }

package/tokens.css

@@ -1,7 +1,6 @@
 /* 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 tokens {
-  :root {
+:root {
     color-scheme: light;
 
     --sf-font-sans: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
@@ -195,4 +194,3 @@
     --sf-colour-link: var(--sf-colour-orange-500);
     --sf-colour-link-hover: oklch(80% 0.14 50);
   }
-}