Color Token Setup — Scope Explainer

What it means & why it matters

What SessDev includes

• Ingestion of the finalized palette through a structured handoff (Figma variables, JSON, or a documented hex list) with one name per color, role, and dark/light pairing.
• Scaffolding of base tokens (raw hex values keyed by brand-color names) and the file layout that keeps the palette in a single source of truth.
• Semantic aliases (surface, text, text-muted, border, accent, accent-hi, danger, success, warning) that components reference by intent rather than raw color name.
• Wiring of the palette into the Tailwind config under theme.extend.colors so utilities like text-text-muted and bg-surface compile correctly.
• Emission of the same palette as CSS custom properties on :root (and a dark-mode selector when in scope) so the values are reachable from non-Tailwind contexts (CMS rich text, embedded widgets).
• Dark and light variants for every semantic alias when the client supplies a paired palette — the same alias resolves to the correct value depending on the active theme.
• Binding of the existing component library to the semantic aliases so visual swaps later (rebrand, sub-brand campaign) require editing only the token file.
• 1 validation pass: lint rule or codemod that flags hardcoded hex values outside the token file, and visual QA that every component renders against both light and dark themes.
• Handoff document listing every token, its raw value, its semantic alias and the procedure to update a value without touching component code.

What is excluded

• Authorship of the palette itself — picking hues, choosing primaries, defining brand color meaning.
• Color-theory consultation, harmony rules, complementary or analogous schemes, color psychology.
• Brand research, competitive color audits, category-color analysis, or any research-driven palette work.
• WCAG-contrast research, contrast-ratio computation for arbitrary text/background pairs, accessibility-driven palette adjustments.
• Accessibility audit of the final UI, color-blindness simulation, low-vision testing or any formal a11y certification.
• Marketing research on color, A/B testing of color choices, conversion-driven palette experiments.
• Competitive analysis or category benchmarking of brand colors.
• Data-visualization palette design — sequential, diverging or categorical scales for charts and dashboards.
• Gradient design, color-stop authorship or motion-gradient composition. Wiring of a supplied gradient is in scope; designing one is not.
• Illustration palette, hero-art color direction or supporting-visual color authorship.
• Authorship of the brand color system — usage rules, do/don't grids, brand-guidelines documentation around color.

Risks if this is mis-configured

• WCAG-contrast failure on the live site

  A palette that looks beautiful in a moodboard can fail WCAG AA on body text against the chosen surface. SessDev wires what the client supplies; if the contrast research was not done, the live site can ship with text that is unreadable for a percentage of users. Contrast research is out of scope and belongs to the design team.

• Brand drift through hardcoded hex

  When engineers in a hurry hardcode hex values inside components instead of using tokens, every rebrand becomes a manual search-and-replace across hundreds of files. The lint rule in scope flags this at CI time, but only if the rule stays enabled. The Care retainer keeps it enforced.

• Hardcoded hex bypassing the token system

  Third-party libraries, copy-pasted snippets and stylesheet imports can sneak hardcoded colors into the bundle. They survive themes (dark mode breaks), they survive rebrands (sub-brand campaigns leak the old palette) and they break consistency. Validation catches the first batch; ongoing discipline prevents the next.

• Dark-mode regression after a token edit

  Editing a single base token without checking the dark-mode alias chain can flip an entire surface to an unreadable color. The semantic-alias layer in scope insulates components from this — provided every alias has a dark/light pair documented in the handoff.

• Token sprawl and naming inconsistency

  Without a naming convention, the token file accumulates 40 near-identical grays and three different danger reds. The handoff defines a fixed naming scheme; deviation from that scheme is what the Care retainer catches at PR review.

• Incomplete palette at handoff

  If the supplied palette covers brand colors but not state colors (danger, success, warning, info) or surface neutrals, SessDev fills the gap from a documented default. That default is intentional engineering scaffolding — not brand design — and should be reviewed by the design team before launch.

• Theme bleed between sub-brands

  When sub-brands or campaign skins are bolted onto the token layer without isolation, one theme's tokens override another in production. The token file in scope supports one primary theme cleanly; multi-theme orchestration is a separate scope item under the Care retainer.

Related scope items

• brand_asset_injectionBrand assets carry the palette in pixel form; tokens carry it in CSS. The two ship together from the same brand handoff.
• typography_integrationTokens and typography are the two halves of the visual system. Same exclusion principle: integration, not authorship.
• icon_library_integrationIcons consume color tokens for currentColor and stroke styling.
• ui_animation_implementationMotion accents reuse accent and state tokens for hover, focus and transition states.
• media_infrastructureImage placeholders and skeleton states reference surface and surface-muted tokens defined here.
• technical_seoTheme-color metadata exposed to browsers and OSes is derived from the primary brand token defined here.

Frequently asked questions

Can SessDev design our color palette?

No. Palette authorship is a design-discipline deliverable and is explicitly out of scope. SessDev wires the finalized palette your design team or external studio delivers.

Do you run WCAG-contrast checks on our palette?

No. Contrast research and WCAG-ratio computation are accessibility-design activities and live with your design team. SessDev wires what the team validates and supplies.

Is dark mode included?

The token layer supports a paired dark/light palette when the client supplies one. Authorship of the dark-mode palette itself is design work and is excluded. Wiring is included.

Will the tokens guarantee accessibility?

No. Tokens are wiring. Accessibility is a function of which values your design team picks and how components compose them. SessDev does not run a formal a11y audit as part of this scope item.

Do you write the brand-color guidelines?

No. Brand-system authorship — usage rules, do/don't grids, brand-guidelines documents — is design-studio work. SessDev ships the engineering layer that those guidelines describe how to use.