SYX is a modular CSS design system with zero external dependencies, built on a 7-layer token architecture,
Atomic Design and native @layer. Compatible with any front-end stack.
Every architectural decision in SYX is driven by keeping CSS predictable, performant, and easy to extend — for teams of any size.
3 application layers (Primitive → Semantic → Component) plus 4 system layers (Layout, Reset, Icon, Theme). A strict CSS variable hierarchy that separates raw values from structural logic, semantic meaning, and per-component implementation.
All specificity in SYX is managed via native CSS @layer.
No hacks, no !important. The cascade finally working for you.
Clearly bounded atoms, molecules and organisms. Each component is a self-contained SCSS mixin
with its own @layer and class namespace.
7 production-ready themes. Each redefines only its semantic tokens — components never change, so switching theme means swapping one stylesheet link, not touching a single component.
Bourbon-compatible: size(), absolute(), transition(),
breakpoint()… Unified patterns that dramatically improve code readability.
Dart Sass only. No Bootstrap, no Tailwind, no JS frameworks. SYX compiles to standard CSS that works in any project: static HTML, React, Vue, Next.js…
A CSS variable system with a strict cascade direction — from the most abstract to the most concrete. Each layer can only reference the one above it, never below.
Numbers, colors and scales without context. Never used directly in components — they are the source of truth for all other layers.
--primitive-color-purple-600
--primitive-space-base
--primitive-font-size-md
Universal layout choices, border-radius, focus ring behaviour and dynamic theme structural decisions. Shared across all components.
--theme-radius
--theme-focus-ring-width
--theme-transition-speed
Functional aliases that carry meaning: primary actions, success states, warnings, errors. Redefined per-theme — components never change.
--semantic-color-primary
--semantic-tone-success-bg
--semantic-color-text-secondary
Component-specific CSS variables that create a stable contract between design and code. Enables robust dark-mode and per-variant overrides without touching component SCSS.
--btn-primary-text
--component-card-padding
--input-border-color
SYX uses native CSS @layer to explicitly order style precedence. The stack covers
everything from the global reset to the highest-priority utilities —
without a single !important or inflated selector.
@layer syx.reset, syx.base, syx.tokens, syx.atoms, syx.molecules, syx.organisms, syx.utilities;
↑ Higher precedence towards the top
Each theme redefines only the semantic tokens. Components stay intact.
Activate a theme by selecting it in the header — or set data-syx-theme="example-XX"
and link the corresponding CSS file.
Theme switching is instant, no page reload required. Try the selector in the header. Combine any theme with dark mode using the ☾ toggle.
SYX is not just AI-assisted — it's AI-operable. Every architectural decision produces a system an agent can read, validate and extend without guessing.
tokens.json, component-registry.json and
contracts/rules.json expose the full surface of the system
as structured JSON — queryable by any agent or pipeline.
syx-validate.js enforces seven contract rules (R01–R07) against
every SCSS file and cross-checks runtime CSS against the token registry —
undocumented tokens, phantom entries and unprefixed legacy vars included.
CI-ready, exits non-zero on violations.
A strict four-layer chain — Primitive → Semantic → Component → Page — means any agent knows exactly where to place a value and what to inherit from. No ambiguity.
_agents/ ships step-by-step workflows
(create-component, create-theme, audit-tokens,
update-changelog) and 9 specialist modes — from the zero-cost
[SYX: SKETCH]: prototyper to the full-depth
[SYX: MIGRATE]: specialist. Every mode opens with two declared blocks:
Trust, the paths it may write, graded by contracts/trust.json
and verified by npm run check:modos — a mode never grants itself a permission,
it inherits one — and Knowledge, the reading list it pulls from
mind-system/. Knowledge informs; it never overrides a rule.
AGENTS.md and CLAUDE.md are tool-agnostic entry points
(OpenAI Codex, Claude Code, Cursor, Copilot) that load AI_GUIDELINES.md,
the contracts layer, and the mode system — so any agent starts with full context
and zero guessing.
npm run export:figma writes the library Figma understands — two
variable collections per theme with light and dark modes, plus the 26 components
with the node property every token maps to. get_figma_spec answers the
same thing one component at a time, over MCP, while an agent draws. Colours arrive as
numeric {r,g,b,a}, not oklch() strings: the conversion is a
function both routes share, so the imported variable and the painted value cannot
diverge. Primitives stay out — by R01, the same rule that governs the CSS.
Run node scripts/syx-validate.js --report to generate a full
audit: runtime surface, phantom tokens, legacy classification, and rule
violations — all in one pass.
Prefix any message with [SYX: MODE]: to route it to a specialist agent —
or /syx MODE … in Claude Code, same grammar, same nine files.
Pick the lowest tier that serves the task; escalate only when the concept is confirmed.
Compose them with → (pipeline) and + (evaluative), where
+ groups first: [SYX: UX → UI + AUDIT]: is
UX → (UI + AUDIT).
| Mode | AI cost | Writes | Best for | Output |
|---|---|---|---|---|
[SYX: SKETCH]:SKETCH Rapid prototyper |
⚡ Minimal 0 files · 1 turn |
nothing | Wireframes, flows, layout POCs — before committing to an idea | Self-contained HTML with inline styles, Mermaid diagrams, handoff note |
[SYX: UX]:UX UX consultant |
🔵 Light 1 file · 1–2 turns |
nothing | Component decisions, HTML structure, accessibility, interaction states, UI hierarchy | Semantic HTML, state inventory, WCAG AA notes, handoff notes for UI mode |
[SYX: CREATIVE]:CREATIVE Experimental creative director |
🟡 Medium 0–1 files · 1–2 turns |
nothing | Experimental landing pages, Awwwards-level concepts, advanced CSS — contract-free zone | Self-contained HTML + CSS, scroll-driven animations, variable fonts, technique log + promotion path |
[SYX: TOKEN]:TOKEN Token architect |
🟠 Medium-high 2 files · 2–3 turns |
prvia propose.js |
Create or migrate tokens, audit the semantic layer, decide primitive → semantic → component mappings | 4-tier token design, tokens.json entries, component token files in scss/abstracts/tokens/components/ |
[SYX: THEME]:THEME Theme designer |
🟠 Medium-high 3 files · 2–3 turns |
nothing recommends only |
Design or revise a theme — OKLCH scales, dark mode inversion, surface token coverage. A theme reaches all seven bundles at once, so the mode designs it in full and a person installs it | OKLCH scales, full _theme.scss, surface token coverage, dark mode variant |
[SYX: UI]:UI Senior SCSS developer |
🔴 High 4+ files · 3–4 turns |
prvia propose.js |
Implement new components or modify existing ones under the R01–R04 contract rules, checked before the file is written | Contract-compliant SCSS, token file, pre-flight checklist, mixin enforcement, registry entry + validation command |
[SYX: AUDIT]:AUDIT QA reviewer |
🔴 High N files · 2–4 turns |
nothing | Validate the contract rules — R01–R04 are errors, R05–R07 warnings, R08 is declared but not yet implemented — plus naming and structure checks | Per-rule verdict report, violations with exact line, correction recommendations |
[SYX: MIGRATE]:MIGRATE Migration specialist |
🔴 Very high N+ files · 4–6 turns |
prvia propose.js |
Replace legacy variables, per-variable impact analysis, safe migration without breaking existing themes | Per-variable migration plan, exact diffs, theme and bundle impact analysis |
[SYX: BRAND]:BRAND Brand identity architect |
🔴 Very high 3 files · 3–5 turns |
recommends | Decide a complete visual identity — colour, typography, space, shape, elevation, motion and state as one coherent set, instead of a recolour. It asks you axis by axis, or decides the lot if you'd rather | The seven axes with their positions and their provenance (yours, the AI's, or inherited), an identity contract of falsifiable invariants, and the specification THEME builds the theme from — BRAND decides the direction, THEME writes the file |
What “AI cost” counts. The file column is what a mode has to open
when it can only open files. With the MCP server registered
(npx -y syx-mcp) most of those reads collapse into one call that returns one
answer, and the tier ranks the work rather than the reading. It counts interrogating the
system — tokens, registry, contracts — not the knowledge a mode loads to reason with, which
is a separate axis declared per mode.
Clone the repository, compile with Dart Sass and link the appropriate bundle to your page. A complete design system running in under 5 minutes.
sass scss/styles-theme-syx-sketch.scss css/styles-theme-syx-sketch.css