Color Foundation
Build an AI-ready Color Foundation without starting from scratch
Turn scattered color values into a semantic system your team can customize, document, and hand off to development
Trusted by designers from
Color gets messy when decisions are made case by case. Most teams lack shared rules for roles, tokens, and implementation
_
Most color systems stop before they become usable infrastructure
Having colors is not the same as having roles, rules, states, themes, and handoff logic
of teams connect tokens across design tools, code, and documentation
Source: zeroheight, 2026
+
of developers and designers say handoff between design and code could be improved
Source: Figma, 2025
1
Raw values
Colors chosen locally without shared naming or system logic
2
Color styles
Colors grouped as reusable styles by hue or brand category
3
Primitive tokens
Palette values organized into named token ranges and steps
4
Semantic roles
Tokens mapped to product roles, states, surfaces, and actions
5
Documented rules
Rules explain usage, contrast, state behavior, and edge cases
6
System layer
AI context, handoff, themes, and team knowledge work from one model
Bring structure to your color system, wherever you're starting from
Start from scratch, clean up existing color tokens, prepare handoff, or customize your semantic color system with AI
Start with meaning, not just #hex
Turn color values into roles, usage rules, and token architecture from day one
Turn your palette into a system
Audit existing colors, fill semantic gaps, and clean up inconsistent usage
Use AI without breaking semantics
Adapt colors with AI while keeping semantic roles and contrast rules intact
Bridge between design and code
Connect color roles to token meaning, state logic, and implementation rules
From scattered color values to a structured color system
Turn palette values into semantic roles, state logic, accessibility rules, and developer-readable handoff
Palette values without semantic meaning
Semantic color roles with clear usage logic
Disconnected text, icon, surface, and border colors
Connected fg, bg, surface, and border roles
Developers guess which token to use
Developer-readable semantic color handoff
State colors created case by case
Shared state logic for hover, focus, error, and disabled
Accessibility checked late
Contrast and visibility guidance built in
Theme support added late or missing
Theme-ready roles for light and dark modes
Turn raw color values into
clear system roles
Replace disconnected colors with semantic roles for surfaces, text, icons, borders, states, and handoff
Before
Raw palette values, mixed usage, unclear meaning, and repeated decisions
After
Semantic roles, state logic, usage rules, and developer-readable handoff
Customize, document, and hand off your color foundation
Adapt color roles, document decisions, and give developers the logic behind the values
Figma file
fig
Build from a structured color foundation with tokens, semantic roles, states, and documentation in one file
Setup guide
Customize your palette, semantic roles, and workflow step by step without breaking the system structure
AI prompts
Audit colors, adapt roles, review accessibility risks, and prepare handoff with repeatable prompts
AI context
Md
Give an LLM the color rules and constraints for safer customization
Gemini Notebook
Md
Explore the system and generate briefings from one source
Accessibility
Md
Review contrast, state colors, visibility, and color-only risks
Dev handoff
Md
Explain token meaning, state logic, and implementation rules
Make color decisions easier for devs to implement consistently
The dev handoff file explains token meaning, state logic, and usage rules before developers implement from Figma
Token meaning
Explain what each semantic color role is for and when it should be used
State logic
Clarify hover, focus, error, disabled, and other state behavior across surfaces
Usage rules
Show where color roles should and should not be used to avoid local exceptions
Implementation notes
Give developers the logic behind the values, naming, and implementation rules
Use AI with color system context,
not generic prompts
Give Claude or another LLM the rules, constraints, and color logic it needs to help without inventing a new system
OpenAI frames context optimization as a core lever for improving LLM accuracy
Source: OpenAI, LLM Accuracy Guide
Role-safe changes
Adapt surfaces, states, and naming without breaking the system model
System-aware audit
Find missing roles, disconnected values, and inconsistent usage
Accessibility review
Check contrast, disabled states, visibility, and color-only risks
Handoff-ready notes
Turn color logic into clearer explanations for developers
Design Systems Surf has helped me conceptualize a framework to move from idea to a usable brand design system. It has taken my prototypes to the next level
Michelle Exantus
UX Researcher
Use Color Foundation when color decisions get messy
Whether you are starting from scratch, cleaning up existing colors, adapting a brand palette, or preparing developer handoff
Start from scratch with color system
When you are building a new product or design system, color decisions can turn into disconnected values quickly. Color Foundation gives you a semantic structure from day one: palette values, roles, states, documentation, AI context, accessibility notes, and developer handoff
Outcome
You start with a color foundation that is ready to customize instead of inventing every rule from zero
Adapt a brand palette into a system
Audit messy colors and gaps
Prepare handoff without guesswork
Deliver client-ready color foundations
Built for teams and designers working on color systems
Use Color Foundation when color decisions need to be structured, customized, documented, and handoff
01
Product designers
Keep product consistent with reusable color roles for surfaces, states, and flows
02
UI designers
Turn visual color choices into clear rules for text, icons, borders, and surfaces
03
Freelancers and agencies
Deliver client-ready color foundations with documentation, AI context, and handoff
04
Design system leads
Standardize existing color decisions with clearer roles, states, and usage logic
Based on analysis of 100+ design systems. Patterns translated into a reusable color foundation
Since 2023, Design Systems Surf has cataloged mature design systems across foundations, components, documentation, and implementation patterns.
Color Foundation turns that research into reusable roles, states, AI context, accessibility guidance, and handoff.
Save 32–58 hours on color system work and documentation
Color Foundation removes repetitive setup, documentation, AI context, accessibility, and handoff work
Trusted by designers working on design systems
Feedback from people building, auditing, documenting, and maintaining design systems
10k+
Designers across 175+ countries follow Design Systems Surf for design system examples, patterns, and practical resources
What to know before you start
Clear answers about what Color Foundation includes, how it can be customized, and how it fits into real design system work
Is this just a Figma template?
No. The Figma file is one part of the package. Color Foundation also includes AI context .md, NotebookLM source .md, setup guidance, AI prompts, accessibility .md, and dev handoff .md.
The Figma file gives you the working color system. The Markdown files support different AI workflows: customization, knowledge exploration, accessibility review, and developer handoff.
What is included?
Color Foundation includes a Figma file, AI context .md, NotebookLM source .md, setup guide, AI prompts, accessibility .md, and dev handoff .md.
The Figma file gives you tokens, semantic roles, states, modes, and documentation. The Markdown files give AI tools the system context needed to help you customize, explore, review, document, and hand off your color foundation with less guesswork.
Can I customize it?
Yes. You can adapt primitive color values, map your brand palette into semantic roles, and adjust state, surface, foreground, background, and border logic.
The goal is to customize the color system without breaking semantic structure, naming logic, accessibility review, or implementation meaning.
Will this fit my brand?
Color Foundation is not tied to one fixed visual palette. You bring your brand colors and map them into product-ready semantic roles.
If your brand palette has gaps, for example missing accessible foreground/background pairs or unclear state colors, the setup workflow and AI-ready Markdown files help you identify what needs review before implementation.
Can I use it with an existing design system?
Yes. You can use Color Foundation as a reference model to audit or repair an existing color system.
It can help you find missing semantic roles, inconsistent state colors, unclear surface rules, weak accessibility constraints, and gaps in developer handoff logic. You do not need to replace your whole design system to use it.
Do I need to use AI?
No. You can use the Figma file and setup workflow manually.
AI is optional, but several supporting files are designed primarily for AI-assisted workflows. The AI context .md helps with safe customization. The NotebookLM source .md helps with knowledge exploration, Q&A, and briefings. The accessibility .md helps AI review foundation-level color risks. The dev handoff .md helps AI generate developer-facing implementation notes.
Are the Markdown files standalone guides?
They are Markdown files, but they are not all traditional standalone guides.
You can read them manually, but their main purpose is to support AI-assisted workflows. Each .md file has a different role: customization context, NotebookLM knowledge source, accessibility review context, or developer handoff context.
What does the NotebookLM source do?
The NotebookLM source .md is a structured knowledge file for exploring the color foundation.
You can upload it to NotebookLM and ask questions about color roles, token meaning, usage rules, accessibility concerns, and implementation logic. It helps turn the foundation into a searchable knowledge source for you, your team, or your client.
What does the accessibility file do?
The accessibility .md is designed mainly for AI-assisted review.
It gives AI the review logic for foundation-level color risks such as contrast, visibility, disabled states, state colors, focus visibility, and color-only meaning. It does not guarantee accessibility by itself. You still need to review the actual values and product usage after customization.
What does the dev handoff file do?
The dev handoff .md is designed mainly for AI-assisted handoff generation.
It gives AI the structure to generate developer-facing notes from your customized foundation, including semantic token meaning, state logic, usage rules, implementation risks, and CSS-oriented token mapping. Developers still need to adapt the output to their codebase, naming conventions, and token pipeline.
Does this include components?
No. Color Foundation covers the color foundation layer: primitive tokens, semantic roles, state logic, surface and foreground relationships, accessibility review logic, and developer handoff context.
It may include examples that show how the color roles work, but it is not a production component library.
Does this support dark mode?
The semantic token structure supports light and dark theme logic. You can use the setup guide and AI-ready Markdown files to extend or review theme roles.
You still need to review your actual color values for contrast, visibility, and state behavior after customization.
Who is this for?
Color Foundation is for product designers, UI designers, freelancers, agencies, design system leads, design system engineers, consultants, and teams that need to build, repair, document, review, or hand off a semantic color system.
Is this for beginners or advanced teams?
Both, but for different reasons.
For newer teams, it gives a structured starting point instead of a blank canvas. For mature teams, it works as an audit, repair, documentation, and handoff reference for weak or inconsistent color foundations.
How is this different from building it myself?
You can build this yourself. The difference is that you would need to create the token architecture, semantic roles, state logic, setup workflow, AI context, NotebookLM source, prompts, accessibility review logic, and handoff structure from scratch.
Color Foundation gives you that structure so you can focus on adapting it to your product, brand, team, or client.
Will developers be able to use it?
Yes, but not as a drop-in code package.
The dev handoff .md helps generate developer-facing notes from the foundation. It explains semantic token meaning, state logic, usage rules, implementation risks, and CSS variable mapping. Developers still need to adapt the output to their codebase and implementation workflow.
Can I use this for client work?
Yes. You can use Color Foundation as part of paid client work and deliver a customized foundation to your client.
You cannot resell, redistribute, or repackage the original product as a standalone product or template unless the license explicitly allows it.
What is not included?
Color Foundation is not a UI kit, component library, brand identity package, palette generator, or automatic accessibility guarantee.
It gives you the foundation structure, workflow, AI-ready Markdown files, review logic, and handoff structure. You still need to customize values, review the result, and adapt implementation to your product or client environment.
Still have questions?
Reach out at hey@designsystems.surf
