CLAUDE.md — AI Coding Instructions for AMB Consulting

This file tells AI assistants (Claude Code and others) how to work safely with this codebase.

Project Overview

AMB Consulting — a Jekyll 3.9.5 static site (Sass/SCSS pipeline).

Layer	Files
Templates	`_layouts/`, `_includes/`
Pages	`*.html` at repo root and `_pages/`
Styles	`_sass/` (partials), compiled to `assets/css/main.css`
Design tokens (SCSS source)	`_sass/_variables.scss`
Design tokens (CSS runtime)	`assets/css/tokens.css`
Component specs	`specs/components/`
Foundation specs	`specs/foundations/`
Token reference	`specs/tokens/token-reference.md`

Design System Rules

Before writing or modifying any UI code

Read the relevant spec file in specs/ for the component you are editing.
Use only tokens defined in _sass/_variables.scss. Never introduce raw rgba(255,255,255,…), raw hex brand colors, or bare font-family strings.
Run the token audit before committing:
```
node scripts/token-audit.js
```
Zero violations required. The script exits 1 if any violations are found.

Token hierarchy

_sass/_variables.scss   ← SCSS source of truth (edit here to add tokens)
       ↓
_sass/_base.scss        ← :root { } bridge exposes tokens as --token-* CSS vars
       ↓
assets/css/tokens.css   ← 3-layer runtime CSS custom property system
                           (consumed by JS and any non-SCSS context)

Single source of truth: _variables.scss. Changes to a token value must happen there only. tokens.css and _base.scss reference SCSS variables — they are generated from it.

Token quick-reference

Instead of…	Use…
`rgba(255,255,255, 0.X)`	`$on-dark-XX` (see `specs/foundations/color.md`)
`rgba(255,255,255, 0.0X)`	`$surface-glass-dark-XX`
`rgba(0,0,0, 0.X)`	`$overlay-*`
`'Inter', sans-serif`	`$font-body`
`'Cinzel', serif`	`$font-heading`
`'Cormorant Garamond', serif`	`$font-display`
`0.35s`	`$normal`
`0.2s`	`$fast`
`0.6s`	`$slow`
`cubic-bezier(0.4,0,0.2,1)`	`$ease`
`#c8a84b`	`$gold`
`#1c0811`	`$maroon`

Component Specs

Every major UI component has a spec in specs/components/. Read the relevant spec before editing a component.

Spec file	Component
`specs/components/button.md`	`.btn`, `.btn--primary`, `.btn--outline`
`specs/components/nav.md`	`#nav`, `.mobile-menu`
`specs/components/hero.md`	`#hero` (home page only)
`specs/components/service-card.md`	`.service-card`
`specs/components/team-card.md`	`.team-member-card`, `.team-modal`
`specs/components/testimonials.md`	`.tcard`, testimonials carousel
`specs/components/gallery.md`	`.gallery-grid`, `.video-card`
`specs/components/contact-form.md`	`.contact-form`, `.form-*`
`specs/components/footer.md`	`#footer`
`specs/components/admin-panel.md`	`#admin-panel`, `#admin-fab`

Foundation Specs

Spec file	Covers
`specs/foundations/color.md`	Brand palette, semantic text, on-dark scale, borders, overlays, feedback
`specs/foundations/spacing.md`	4px base scale, layout variables
`specs/foundations/typography.md`	Font families, type scale, weights
`specs/foundations/radius.md`	Border radius (sharp aesthetic)
`specs/foundations/elevation.md`	Shadows and z-index scale
`specs/foundations/motion.md`	Duration, easing, keyframe patterns
`specs/tokens/token-reference.md`	Master map: SCSS var → CSS var → raw value

SCSS Conventions

All partials live in _sass/ and are imported by main.scss.
One partial per concern (e.g., _nav.scss, _hero.scss). Do not dump unrelated styles into _base.scss.
Nest selectors at most 2 levels deep to keep specificity manageable.
Do not use !important except in utility overrides.
Mobile-first responsive styles go in _sass/_responsive.scss.

Jekyll / Liquid

All page layouts extend _layouts/default.html.
Shared fragments live in _includes/ (e.g., nav.html, footer.html).
Data files live in _data/ (YAML). Content that changes frequently (team bios, testimonials) is sourced from _data/ — do not hardcode it in HTML.
The admin panel writes to these data files via the admin API endpoint.

Do Not

Do not add inline style="" attributes — use SCSS tokens and classes.
Do not introduce new npm/yarn dependencies without discussion.
Do not modify assets/css/main.css directly — it is generated by SCSS compilation.
Do not commit without running node scripts/token-audit.js first.