design-system

Design System: standards + safe evolution (gotodive.com block theme)

Invocation: /design-system $1

• audit — scan the theme for design-consistency violations.
• tokens — print the canonical token reference.
• component <name> — explain/locate a .gtd-* component.
• change <description> — make a design change THROUGH the system (not ad-hoc).

Theme root: themes/gotodive-com/. Tokens live in theme.json; the design system (component classes, hovers, responsive) lives in assets/theme.css.

Single source of truth

• COLORS / FONTS / SPACING are defined ONCE in theme.json and consumed as var(--wp--preset--color--<slug>) etc. NEVER hardcode a hex that duplicates a token. If a value isn't a token yet, add it to theme.json first.
• COMPONENTS (.gtd-*) are defined ONCE in assets/theme.css. Reuse them; do not invent one-off inline component styling in patterns.

Canonical tokens (mirror of theme.json — keep in sync when theme.json changes)

Color palette (slug -> hex -> role):

• base #f1f4f2 Mist — page background / no-bg sections
• surface #ffffff — white cards / courses section
• surface-2 #e8f1ed Seafoam Tint — alternating panel sections
• contrast / primary #2d4c4f Ocean Deep — body text, dark blocks, headings
• primary-dark #223a3c — gradient end, deepest teal
• contrast-2 #5f767a Muted — captions, stat labels, meta
• secondary #ff5600 Orange — CTA / accent / links on dark
• accent #a3c9c1 Seafoam — chips, soft accents
• border #dbe2dd Soft Stone — hairlines, card borders Gradients: ocean-soft (mist->seafoam, light panels) ; ocean-hero (teal, dark covers). Typography: heading = EB Garamond serif ; body = Inter ; mono = Space Mono (eyebrows/stats/labels). Sizes: small/medium/large/x-large/xx-large/huge (fluid). Spacing scale (slugs): 20=.75 / 30=1.25 / 40=2 / 50=3 / 60=4.5 / 70=6 rem. Layout: contentSize 760px, wideSize 1200px. Mobile breakpoint ~781px.

Component library (.gtd-*, in assets/theme.css)

• Surfaces: .gtd-pebble-card, .gtd-blob-media, .gtd-glass-card, .gtd-dark (primary bg + light text), .gtd-grain (felt texture overlay).
• Labels: .gtd-eyebrow (mono uppercase coral; .is-pill, .has-dot, .on-dark).
• Accents: .gtd-icon-circle (.is-seafoam / .is-coral), .gtd-stat-num (mono coral).
• Lists/CTAs: .gtd-cred-list, .gtd-stat-row, .gtd-eu-cta, .gtd-article-card, .gtd-tag, .gtd-progression-chain, .gtd-roadmap/.gtd-step, .gtd-activity-*.
• Buttons: core button + backgroundColor:secondary (coral CTA) or .gtd-btn-glass.
• Header/footer: .gtd-brand, .gtd-logo-dot, .gtd-header, footer dark teal.

Hard standards (do / never)

• NEVER put a <style> block in any theme .php/.html. Style via theme.css.
• Inline style="" in patterns is allowed ONLY for genuine block-editor output (spacing, cover gradients, on-dark text). Do not use it as a component.
• On .gtd-dark blocks, links must use coral (.gtd-dark p a) — inherited dark link color is invisible on dark bg.
• Encoding-proof punctuation: use HTML entities for separators in theme files (· for ·, → for →) so a bad deploy can't turn them into ??.
• Keep dividers/section backgrounds within the cool-neutral family (base/surface/ surface-2). Do not reintroduce warm tones (peach/cream) — they create visible warm/cool seams between sections.

Change workflow (/design-system change ...)

1. Decide if it's a TOKEN change (theme.json) or a COMPONENT change (theme.css). Prefer token changes for palette/typography/spacing.
2. Edit the source file (theme.json or assets/theme.css). For a new reusable visual, add a .gtd-* class — never inline it per pattern.
3. Bump style.css Version header (cache-bust the enqueue).
4. Deploy via the safe-deploy skill (backup -> diff -> confirm -> chmod 644 -> cache flush -> live-verify). Re-set SSH env first if the shell is fresh.
5. VERIFY: Playwright desktop 1366x900 + mobile 390 on the affected sections; confirm no overflow, consistent spacing, correct colors, no ?? in HTML.

Audit loop (/design-system audit) — repeat until zero violations

Scans across themes/gotodive-com/:

• Stray <style> blocks: grep -rn "<style" themes/gotodive-com -> MUST be 0.
• Hardcoded hex that duplicates a token (e.g. #5f767a, #2d4c4f, #ff5600) outside theme.json -> replace with the token / a class.
• Mojibake / ?? in files (delegate to precheck encoding guard).
• Token drift: any color/font/spacing in theme.css that isn't a var(--wp--preset--*) and isn't an intentional one-off. For each violation: fix at the source (token or component), re-run the audit. Stop when clean; report the before/after list.

Known accepted exceptions (not violations)

• #ffffffcc (semi-white text) on dark blocks — intentional.
• Cover gradient rgba(45,76,79,...) in hero.php — block-editor cover output.
• #5f767a stat labels in founders.php — equals the contrast-2 token value; optional to tokenize via has-contrast-2-color, cosmetic only.