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.
6 production-ready themes. Each redefines only its semantic tokens — components never change. Switching theme is a single HTML attribute change.
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 four contract rules (R01–R04) against
every SCSS file and cross-checks runtime CSS vs token registry.
CI-ready, zero false positives.
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 8 specialist modes — from the zero-cost
[SYX: SKETCH]: prototyper to the full-depth
[SYX: MIGRATE]: specialist. Each mode has a defined role, a resource tier,
and constrained output, so the right expertise activates before any response is generated.
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.
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.
8 modes ordered by resource cost — from a zero-context sketch to a full codebase migration.
Pick the lowest tier that serves the task; escalate only when the concept is confirmed.
| Mode | AI cost | Best for | Output |
|---|---|---|---|
[SYX: SKETCH]:SKETCH Rapid prototyper |
⚡ Minimal 0 files · 1 turn |
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 |
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 |
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 |
Create or migrate tokens, audit the semantic layer, decide primitive → semantic → component mappings | 4-tier token design, tokens.json entries, _token.scss files |
[SYX: THEME]:THEME Theme designer |
🟠 Medium-high 3 files · 2–3 turns |
Create or modify themes, OKLCH color scales, dark mode inversion, surface token coverage | OKLCH scales, full _theme.scss, surface token coverage, dark mode variant |
[SYX: UI]:UI Senior SCSS developer |
🔴 High 4+ files · 3–4 turns |
Implement new components or modify existing ones with full R01–R08 contract compliance | 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 |
Validate R01–R08 compliance, detect naming and structure violations, codebase health check | Per-rule verdict report, violations with exact line, correction recommendations |
[SYX: MIGRATE]:MIGRATE Migration specialist |
🔴 Very high N+ files · 4–6 turns |
Replace legacy variables, per-variable impact analysis, safe migration without breaking existing themes | Per-variable migration plan, exact diffs, theme and bundle impact analysis |
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/themes/example-01/bundle-home.scss css/theme-01-bundle-home.css