SYX Design System

Authoring Guide

Practical decision rules for writing HTML and SCSS with SYX. Read this before creating any component.

<nav aria-label="Main navigation" class="org-navbar">
  <ul class="org-navbar__list" role="list">
    <li><a href="/" class="atom-link">Home</a></li>
  </ul>
</nav>

<div class="org-navbar">
  <div class="org-navbar__list">
    <div><span class="atom-link">Home</span></div>
  </div>
</div>

<!-- ✅ Correct -->
<button class="atom-btn atom-btn--primary">          <!-- block + modifier -->
  <span class="atom-btn__icon" aria-hidden="true">   <!-- element -->
</button>
<button class="atom-btn is-loading">                <!-- dynamic state -->

<!-- ✅ Composed in HTML — molecules inside organisms -->
<header class="org-header">
  <div class="org-header__inner layout-grid">
    <a href="/" class="atom-link org-header__logo">…</a>
    <nav class="org-navbar">…</nav>
    <div class="mol-btn-group">
      <button class="atom-btn atom-btn--ghost">Log in</button>
      <button class="atom-btn atom-btn--primary atom-btn--filled">Sign up</button>
    </div>
  </div>
</header>

<!-- ❌ Wrong — organism SCSS references a molecule selector -->
/* organisms/_header.scss */
.org-header .mol-btn-group { margin-left: auto; } ← coupling between layers

<!-- ✅ Icon-only button done right -->
<button class="atom-btn atom-btn--ghost atom-btn--circle"
        aria-label="Close menu">
  <span class="atom-icon atom-icon--lc-x" aria-hidden="true"></span>
</button>

<!-- ✅ Standard responsive layout -->
<main class="layout-grid">
  <div class="layout-grid__col-xs-12 layout-grid__col-md-8"><!-- main --></div>
  <aside class="layout-grid__col-xs-12 layout-grid__col-md-4"><!-- sidebar --></aside>
</main>

<!-- ✅ Full-bleed section with constrained inner content -->
<section class="org-hero">
  <div class="layout-grid">
    <div class="layout-grid__col-xs-12 layout-grid__col-md-8 layout-grid__col-lg-6">
      <h1 class="atom-title atom-title--h1">…</h1>
    </div>
  </div>
</section>

.org-header {
  &__nav {         // level 2
    &--open { … } // level 3
  }
}
// Output: .org-header__nav--open {}

.org-header {
  &__nav {
    &__list {
      &__item {
        &--active { … }
// Output: .org-header__nav__list__item--active

// ✅ Correct
@mixin mol-card($theme: null) {
  @layer syx.molecules {
    .mol-card { /* base */ }
    .mol-card--featured { /* modifier */ }
  }
}

// Called from themes/example-01/_setup.scss:
@include mol-card("example-01");

// ❌ Wrong — top-level rules cannot be excluded from any bundle
.mol-card { … }

// ✅ Only emits padding-top and padding-bottom — no left/right
@include padding(var(--semantic-space-inset-md) null);

// ❌ Raw CSS always emits all 4 properties (sets left/right to 0)
padding: var(--semantic-space-inset-md) 0;

// ✅ Horizontal centering without touching top/bottom
@include margin(null auto);
// → margin-right: auto; margin-left: auto;

.syx-component {
  // 1. Positioning
  @include absolute($top: 0, $left: 0);

  // 2. Display / Box model
  @include flex-center();

  // 3. Dimensions
  @include size(100%, 48px);

  // 4. Spacing
  @include margin(null auto);
  @include padding(var(--component-x-inset-y) var(--component-x-inset-x));

  // 5. Typography
  font-size: var(--component-x-font-size);
  color: var(--component-x-color);

  // 6. Visual
  background-color: var(--component-x-bg);
  @include border(all, 1px, solid, var(--component-x-border));
  @include border-radius(var(--component-x-radius));
  box-shadow: var(--component-x-shadow);

  // 7. Transitions — ALWAYS before states
  @include transition(color 0.2s ease, background-color 0.2s ease);

  // 8. States
  &:hover { … }
  &:focus-visible { @include focus-ring(); }
  &:disabled { … }
  &--modifier { … }

  // 9. Elements (__element)
  &__icon { … }
  &__label { … }
}

// ✅ Mobile-first with breakpoints
.org-hero__title {
  font-size: var(--semantic-font-size-xl);      // mobile

  @include breakpoint(tablet) {
    font-size: var(--semantic-font-size-2xl);   // tablet+
  }
  @include breakpoint(desktop) {
    font-size: var(--semantic-font-size-display); // desktop+
  }
}

// ✅ Focus ring only inside :focus-visible
&:focus-visible { @include focus-ring(); }

❌ <div class="syx-card-featured"> → this is a molecule, not a utility
✅ <div class="mol-card mol-card--featured">

❌ @include color(var(--component-x-color));  → doesn't exist, adds no value
✅ color: var(--component-x-color);
✅ opacity: 0.5;
✅ cursor: pointer;
✅ z-index: var(--semantic-z-index-dropdown);

❌ .org-header .atom-btn--primary { background: red; }  → forced specificity
✅ Use .syx-* utilities — they always win via @layer syx.utilities

// ❌ Only in themes/example-02/_theme.scss:
--component-header-bg: hsl(0, 0%, 5%);  → themes 01,03,04,05 get no value

// ✅ Always define the fallback in abstracts/tokens/components/_header.scss:
--component-header-bg: var(--semantic-color-bg-primary); // default
// Then override only in the theme that needs it

// _bundle-full.scss → passes the theme name to the mixin, once for all themes
@include org-site-header($theme);

// organisms/_site-header.scss → two methods based on type of difference
@mixin org-site-header($theme: null) {
  // Method 1 — CSS token (automatic, all themes)
  background: var(--component-header-bg);

  // Method 2 — direct @if (1–2 themes only)
  @if $theme == "example-02" { backdrop-filter: blur(8px); }
}

// postcss.config.js — safelist
safelist: [/^atom-btn--/, /^is-/];

// Or include class names in an HTML comment (PurgeCSS scans content):
<!-- is-open is-active is-loading atom-btn--danger -->

1 — Ask: the MCP server and the Node API

Two front doors, one implementation (scripts/lib/consulta.js). An agent speaking MCP and an application calling require() must get the same answer to the same question — two copies of a criterion always end up disagreeing.

{
  "mcpServers": {
    "syx": { "command": "npx", "args": ["-y", "syx-mcp"] }
  }
}

const syx = require('syx-design-system');

syx.getToken({
  token: '--component-button-primary-filled-bg',
  theme: 'syx-sketch', mode: 'dark'
}).value;   // → oklch(0.740 0.133 267)

The ten tools

No dependencies: plain JSON-RPC over stdio. Everything about tokens and classes is arbitrated against the compiled CSS, so what comes out of it exists.

2 — Write: graded trust

Reading is safe; writing is not. What an agent may change is graded by how far the change travels — the boundary follows the direction of the cascade this system already declares. The tiers live in contracts/trust.json, as data, so they can be read without running anything.

The proposal path

# Where does this change sit?
npm run propose classify scss/atoms/_btn.scss CHANGELOG.md

# Propose a component token — nobody says which file it goes in
npm run propose token -- --name --component-feature-card-glow \
  --value "var(--semantic-shadow-md)" --why "Optional lift for the featured card"

The destination is deduced from the token's family — which file already declares --component-feature-card-* — never from a lookup table that would quietly go stale. Then the tool writes it, recompiles the CSS, runs the validator over the result, and only if that is green does it create a branch, a commit and an evidence file in contracts/propuestas/. If it is not green, there is no branch. Review starts with the proof in front of you instead of a claim that it works. It never pushes: it prints the command.

What it refuses, and says why

3 — Detect: drift in a consuming app

A design system only stays a system if what ships still matches it. syx-scan reads an app's HTML and CSS and reports where it has drifted — comparing against the version of SYX that app has installed, which is the only comparison that means anything.

npx syx-scan "src/**/*.html" src/app.css   # from a consuming app
npm run scan -- docs.html --todo           # from this repo
npx syx-scan app/ --json > drift.json      # for CI

4 — What runs on its own

None of the above is worth much if it only runs when somebody remembers. npm run check chains twelve checks and a build, and GitHub Actions runs them on every push across Node 18, 20 and 22 — with the heavier ones (packing and installing the package for real, exercising the proposal path) reserved for pull requests, so nobody is tempted to switch it off.

5 — What this buys you

The argument is not that agents stop making mistakes. It is that the expensive mistakes become cheap to catch, and the cheap ones stop happening at all. Every figure below is measured in this repository, not estimated.

The short version: a design system stops being documentation an agent has to believe, and becomes a service it can query and a gate it has to pass. Everything above follows from that one change.

6 — Four worked examples

Every block below is literal output, captured by running the commands against this repository at v4.25.0. Nothing is mocked up; where a transcript ran long it was cut at a line boundary and marked, never reworded.

6.1 — An agent asks before it writes

The task: make the featured card react on hover. Five calls over MCP, not one file opened. Watch the third — the rule stops the agent and hands it the replacement, which is the half that used to be missing.

1 · What is it, and which tokens does it consume?

→ get_component { "name": "feature-card" }

{
  "encontrado": true,
  "name": "feature-card",
  "layer": "molecule",
  "classes": [
    "mol-feature-card"
  ],
  "file": "scss/molecules/_feature-card.scss",
  "tokens": [
    "--component-feature-card-bg",
    "--component-feature-card-border-color",
  …

2 · What colour does its border actually become on hover?

→ get_token { "token": "--component-feature-card-border-color-hover" }

{
  "encontrado": true,
  "value": "oklch(0.239 0.014 267)",
  "theme": "syx-sketch",
  "mode": "light",
  "cadena": [
    {
      "token": "--component-feature-card-border-color-hover",
      "declarado": "var(--semantic-color-border-strong)"
    },
    {
      "token": "--semantic-color-border-strong",
      "declarado": "var(--primitive-color-ink)"
    },
  …

3 · A snippet written from memory

→ validate_snippet { "code": ".mol-feature-card {\n  transition: transform 0.2s ease;\n  position: relative;\n}" }

{
  "conforme": false,
  "violaciones": {
    "R03": {
      "regla": "Sin `transition:` en crudo — usa el mixin transition()",
      "casos": [
        {
          "file": "scss/molecules/_feature-card.scss",
          "line": 2,
          "content": "transition: transform 0.2s ease;"
        }
      ],
      "recambio": {
        "mixin": "transition",
        "signature": "transition($props...)",
        "alias": [],
        "ejemplo": "  @include transition(opacity 0.2s ease, transform 0.3s ease);"
      }
    }
  }
  …

4 · So how is that mixin written?

→ get_mixin { "name": "transition" }

{
  "encontrado": true,
  "signature": "transition($props...)",
  "params": [
    {
      "name": "$props",
      "variadic": true
    }
  ],
  "emits": [
    "transition"
  ],
  …

5 · The same snippet, now using the system

→ validate_snippet { "code": ".mol-feature-card {\n  @include transition(transform 0.2s ease);\n  @include relative();\n}" }

{
  "conforme": true,
  "violaciones": {},
  "tokensInexistentes": []
}

The keys come back in Spanish — encontrado, cadena, declarado. That is the real payload, not a translation: the contract layer was written in the language its author thinks in, and these transcripts were not touched up to hide it.

The alias chain in call 2 is the point: the agent didn't resolve the cascade, it was handed component → semantic → primitive → the literal value the browser paints. And in call 5 the same snippet comes back conforme: true.

6.2 — A proposal, end to end

Nobody says which file the token belongs in.

   token        --component-feature-card-glow
   valor        var(--semantic-shadow-md)
   destino      scss/abstracts/tokens/components/_cards.scss   (junto a --component-feature-card-bg)
   deducido de  familia «feature-card», 2 segmento(s) en común
   nivel        Vía propuesta — El alcance está acotado a un componente. Es reversible de un vistazo, pero toca CSS que se envía a producción.

   escrito en scss/abstracts/tokens/components/_cards.scss:26

   compilando y validando…
Switched to a new branch 'syx/token-component-feature-card-glow'

✅ Rama syx/token-component-feature-card-glow lista, un commit, validación en verde.
   evidencia    contracts/propuestas/component-feature-card-glow.md
   volver       git checkout principal

   Para publicarla:
   git push -u origin syx/token-component-feature-card-glow && gh pr create --fill --body-file contracts/propuestas/component-feature-card-glow.md

2bd75c1 feat(tokens): --component-feature-card-glow

And the evidence it leaves beside the commit, which is what a reviewer opens first:

# Propuesta — `--component-feature-card-glow`
**Generada por** `scripts/propose.js` · 2026-08-31T22:15:14.771Z · SYX v4.25.0
## Qué
| | |
|---|---|
| Token | `--component-feature-card-glow` |
| Valor | `var(--semantic-shadow-md)` |
| Fichero | `scss/abstracts/tokens/components/_cards.scss` |
| Nivel de confianza | Vía propuesta — El alcance está acotado a un componente. Es reversible de un vistazo, pero toca CSS que se envía a producción. |
**Por qué:** Realce opcional para la tarjeta destacada

## Dónde va, y por qué ahí
Nadie lo ha dicho: se dedujo de la familia `feature-card`, que ya vive en ese fichero (`--component-feature-card-bg`). Se insertó al final de su bloque para no partir la agrupación.
…  (sigue el informe completo del validador, y qué revisar)

6.3 — What it refuses, and what it says instead

A system that stops an agent is worth more than one that lets it through. None of these four wrote a single byte.

A primitive

✋ --primitive-color-blue-999 es de la capa «primitive», que vive en scss/abstracts/tokens/primitives/
   Nivel: Solo humano. Un cambio aquí se propaga a los siete temas de golpe, o cambia el criterio con el que se juzga a todo lo demás.

   Lo que sí puede hacer un agente aquí es preparar el análisis: qué temas
   se verían afectados y con qué valores. Escribirlo, no.

A colour written by hand

   El valor es un color literal, y un token de componente debe apuntar a uno semántico.
   Ese color ya es --semantic-color-primary, --semantic-color-border-focus, --semantic-color-link-active, --semantic-focus-ring-color, y 6 más.
   Usa var(--semantic-color-primary) si es el papel que le corresponde.

A family nobody declares

   Ningún token existente comparte familia con «--component-site-header-blur»: sería una familia nueva, y eso es decidir un fichero nuevo, no colocar un token.

   Familias declaradas que se le parecen: header-bg, header-control, header-height, header-logo, header-padding, header-social, header-z, section-header

   Puede que el nombre no siga la familia ya declarada. Si de verdad es nueva, crea el fichero a mano en scss/abstracts/tokens/components/.

A value that skips the semantic layer

   El valor apunta a un primitivo, y un --component-* pasa por --semantic-*.
   var(--primitive-color-blue-500)

   Dar papel a un primitivo es trabajo de la capa semántica, que es solo humana.

6.4 — Auditing a page nobody was watching

This very site, today. It reported six a version ago; four were fixed in v4.25.0 — among them a progress bar that had gone months without painting, because it named a token that exists in no theme.

── DESVIACIÓN RESPECTO A SYX ───────────────────────────────────

   comparado contra    syx-sketch · light · SYX v4.25.0
   ficheros            1
   hallazgos           2   (2 baja)

   Bases sin estilos, con modificadores que sí existen  —  1
   ──────────────────────────────────────────────────────────────
   · why-syx.html:346  .atom-txt no declara nada (38 usos)
      Sus modificadores sí existen (.atom-txt--primary), así que la familia es real y solo falta la base.
      → O la base recibe los estilos que su nombre promete, o sobra en el marcado. Es una decisión de diseño.

   Clases que solo usa el JavaScript  —  1
   ──────────────────────────────────────────────────────────────
   · why-syx.html:233  .syx--theme-syx-sketch no la declara ningún CSS
      El script de la página sí la usa (syx--theme-…): parece un asidero de JavaScript, no una desviación.
      → Si es un asidero, mejor un data-* que una clase: así nadie espera que pinte.

   El escáner no arregla nada a propósito: lo que encuentra entra por
   scripts/propose.js o por las manos de alguien.

7 — Out to Figma

The first six sections are about an agent operating the system from the inside. This one is the same system pointed outward, and the direction is not negotiable: SYX is the source, Figma is a consumer — like an app is a consumer. Nothing here reads a design and writes SCSS.

Ask, per component — while drawing

→ get_figma_spec { "component": "btn", "theme": "syx-sketch", "mode": "dark" }

{
  "figmaName": "atom/btn",
  "clases": { "base": ["atom-btn"], "modificadores": ["atom-btn--primary", …] },
  "propiedades": [
    {
      "token":     "--component-button-primary-filled-bg",
      "variable":  "component/button/primary/filled/bg",
      "propiedad": "fills",
      "tipo":      "COLOR",
      "valor":     { "r": 0.5216, "g": 0.6555, "b": 0.9994, "a": 1 },
      "hex":       "#85a7ff",
      "variante":  "primary",
      "estado":    "default"
    }, …40 in total
  ],
  "sinTraducir": [
    { "token": "--component-button-font-size",
      "motivo": "expresión CSS: solo un navegador la reduce" }, …
  ]
}

Or export the whole library

npm run export:figma   # → contracts/figma/<theme>.figma.json   (7 files)
npm run check:figma    # fails if those files are stale

   example-01    515 variables · 34 componentes · 274 omitidas
   …
   syx-sketch    543 variables · 34 componentes · 247 omitidas

   3635 variables · 1879 omitidas con motivo

Two variable collections per theme — SYX · Semantic and SYX · Component — each with a light and a dark mode, plus the 26 components with the node property every token maps to. Three decisions are worth knowing before you import:

1 — The nine modes

Ordered by tier, which ranks how much context the mode spends. Use the lowest tier that does the job. Start at SKETCH or UX to check the idea is worth anything; escalate to TOKEN → UI → AUDIT once it is confirmed.

2 — Two doors, one room

The prefix is the portable form. It is plain text, so it survives into Claude Code, Codex, Cursor or anything else that ingests AGENTS.md. It is a convention, though: nothing forces a client to honour it.

[SYX: UI]: implement the atom-tag
component with --primary and --neutral

[SYX: AUDIT]: review
scss/organisms/_site-header.scss

/syx UI implement the atom-tag component

/syx UX → TOKEN → UI + AUDIT
     a search field with autocomplete

.claude/commands/syx.md takes the same grammar and resolves to the same nine files. It is a pointer, not a copy, so there is nothing to keep in sync. What it adds is that the harness runs it: autocomplete, and the mode file gets read because the command says so rather than because an agent remembered a convention.

3 — Composing modes

Two operators. → is a pipeline: each mode's output is the next one's input. + is evaluative: both modes work the same artifact and both outputs come back together.

A middle step with no work does not stop the pipeline. If TOKEN finds every token it needed already exists, it hands off explicitly — “use these” — and the chain continues. Aborting is the user's call, not the mode's.

4 — Every mode opens with two blocks

This is the head of _agents/modes/ui.md, unedited. Trust says what the mode may write; Knowledge says what it reasons with.

> **Trust** — graded by `contracts/trust.json`, verified by `npm run check:modos`.
>
> · **Writes:** `scss/atoms/`, `scss/molecules/`, … — tier `pr`: prepare the change
>   with `node scripts/propose.js`. A person merges.
> · **Recommends only:** `scss/abstracts/mixins/`, `scss/base/` — say so and stop there.
> · **Reads:** `contracts/rules.json`, `component-registry.json`, `mind-system/knowledges/`
> · **Ask, don't read:** `get_component` before duplicating one, `get_mixin` before writing
>   a property R03 or R04 rejects, `validate_snippet` **before** writing the file.

> **Knowledge** — the cortex under `mind-system/knowledges/`, routed by `mind-system/routing.md`.
> It informs; it never executes.
>
> · **Always:** `syx/scss-pipeline.md` · `syx/component-patterns.md` · `syx/token-system.md`
> · **When relevant:** `ui/refactoring-ui.md` for spacing and composition calls · …
> · **On request:** `motion/03-patrones/` for a GSAP effect named in the brief

The two are not symmetric in force. A permission is a ceiling; a module is an argument. Knowledge never authorises anything and never wins against a rule — if a module recommends what R01 forbids, the module is what needs fixing.

5 — The engine and the cortex

The modes are the engine. Behind them sits mind-system/, the cortex: colour theory, UX laws, WCAG, scale models, brand perception, a motion language, and the editorial rules of a consuming product. It loads on demand, per the Knowledge block, and it is not published to npm.

Precedence, highest first

A rung never beats one above it. That is the whole rule, and it is what keeps a markdown file from overruling a machine-checked contract. Rungs 1–3 are verified; 4–6 are written down and not yet guarded, which this page says out loud rather than implying otherwise.

Typography Scale — .syx-type-*

Text utilities

Text Colors — .syx-text-*

Social brand

Backgrounds — .syx-bg-* · .syx-bg-color-*

Semantic (_text.scss)

Theme-aware helpers (_backgrounds.scss)

Spacing — .syx-m/p-*

Margin bottom scale (0–5)

Padding scale (1–5) · shorthands

Display · Flex · Gap · Position

.syx-d-flex + gaps + wrap

.syx-justify-between + .syx-items-center

.syx-d-grid + .syx-gap-3

Media — img-fluid · embed · object-fit

.syx-img-fluid

.syx-embed--16by9

Object-fit · Background-size classes

Accessibility — .syx-sr-only · skip-link · motion-safe

Font Sizes — .syx-font-size-*

Responsive scale. Values map to --font-size-1…5 tokens. Sizes 2–5 scale up at $breakpoint-md.

Dimensions — .syx-size-*

Square size tokens mapping to --primitive-size-1…5. For icons, avatars, thumbnails.

layout-grid — xs / sm / md breakpoints

Column spans at xs

Responsive — xs-12 → sm-6 → md-4 (resize to see)

Modifiers: --no-gap · __nested · --is-edge2edge

Breadcrumb

Buttons — .atom-btn

Outline (no --filled) · default size

Filled (--filled) · default size

Sizes — --size-sm · --size-md · --size-lg (outline)

Sizes — filled

Circle — --circle with atom-icon · sm · md · lg

atom-btn--has-icon — icon size + gap auto-controlled by --size-*

States — normal · hover (hover me) · focus-visible (Tab) · disabled

Pills · Labels

Link

Paragraph with an inline primary link — hover to see the fill effect. And another link.

Icons — .atom-icon

Legacy system — --ui-* / --arrow-* / --rrss-*

Lucide — Navigation --lc-*

Lucide — Actions

Lucide — Status · User

Sizes — --sm · --md · --lg · --xl

Color modifiers — --color-primary · --color-state-ok · --color-state-ko · --color-state-warning

Title · Txt

H1 Title

H2 Title

H3 Title

H4 Title

H5 Title

H6 Title

Body paragraph with atom-txt--primary. Includes semantic bottom margin for vertical rhythm.

Second paragraph to demonstrate consistent spacing between text blocks.

Form — label · input · input-wrapper

Check · Switch

Lists

Table

Pagination

Code — syntax highlight

.atom-code — block

.atom-btn {
  background-color: var(--component-btn-primary-bg);
  color: var(--component-btn-primary-color);
  /* token-driven — no hardcoded values */
}

.atom-code--inline

Use @layer syx.utilities to ensure utilities always win.

Radio

Form Field — states

Btn Group · Label Group

mol-btn-group

mol-label-group

Form Field Set — group wrapper

Default (vertical stack)

--inline (horizontal wrap with flex: 1 1 auto)

Site Header — brand + nav + actions

Live example — the header at the top of this page is this organism

Composes: atom-icon · atom-btn · mol-btn-group. Add more organisms to scss/organisms/ and forward from organisms/index.scss.