SYX Design System

Where does my code go? — Decision flowchart

Quick reference

Worked examples

HTML Authoring

2.1 — Semantics first

Always start with the semantically correct element, then apply SYX classes. Never choose an element because of its default browser style.

<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>

2.2 — BEM in HTML

<!-- ✅ 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 -->

2.3 — Compose in HTML, not in SCSS

Organisms and molecules are composed in HTML. Keep SCSS partials free of cross-layer selector references.

<!-- ✅ 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

2.4 — Accessibility (required)

<!-- ✅ 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>

2.5 — Layout Grid

Use .layout-grid for all main content areas. Never invent ad-hoc flex containers for page structure.

<!-- ✅ 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>

SCSS for efficient CSS output

Every SCSS decision carries a cost in the compiled CSS. These rules keep the output lean.

3.1 — Max 3 nesting levels

.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

3.2 — The @mixin wrapper pattern (mandatory)

Every component MUST be wrapped in a @mixin with a $theme parameter. This enables selective inclusion and multi-theme support.

// ✅ 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 { … }

3.3 — Null-safe shorthand

SYX mixins skip null values. Use this to avoid emitting unnecessary properties.

// ✅ 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;

3.4 — Token → CSS output

3.5 — Property order inside a rule

.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 { … }
}

Mixin Deep-Dive

// ✅ 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(); }

Tips, Patterns & Gotchas

❌ <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

// setup.scss → passes the theme name to the mixin
@include org-header("example-02");

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

  // Method 2 — Sass map (structural differences)
  @if theme-cfg($theme, "header-sidenav-side", left) == right { right: 0; }

  // Method 3 — 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 -->

Quick decision checklist

Before writing any new code, ask yourself: