Creating a Design System for a First App: Tokens, Components, and State Documentation

You are building a first app and you need the UI to hold together. You read about design systems, tokens, and component libraries. The gap between a blog post and a working file is where most solo designers stall. Here is a repeatable method to build a design system for a first app, tokens and components that cover every interactive state, without turning into a full-time maintenance job.

A design system is a set of standards, reusable components, and guidelines for UI design and code. That is the Nielsen Norman Group definition from 2023. The minimum viable version for a first app needs exactly these pieces: a color palette, a typography scale, a spacing scale, and four to six core UI components. Brad Frost's Atomic Design methodology, revised in 2022, calls this the skeleton that keeps a product from falling apart on page three.

Over-engineering starts when you add a component you have not used yet. Do not define a tooltip until your app needs one. Do not write a motion guideline until a prototype proves a transition is confusing. The rule: build the token, make the component, ship the screen. If a token has no home in a live component, delete it.

Open Figma and create a single file called Design System. Inside it, make three pages: Tokens, Components, and Documentation. Do not use a community template. Building the structure yourself forces you to understand every choice.

Token Structure That Works

Design tokens are the raw materials. The W3C Design Tokens Community Group draft specification, as of 2024, defines a format for storing them as JSON. You do not need JSON yet. You need a naming convention. Use category type property. Example: color primary default, color primary hover, type scale body large, spacing scale 400.

Material Design 3 uses a token-based approach where a source value generates a full color role set. Your minimum palette needs one primary, one secondary, one surface or background, one error, one on-primary, and one on-surface text color. That is six colors. Add a seventh for disabled if your app has form fields.

Define your type scale in steps. Material Design 3 specifies a scale with display, headline, title, body, and label tiers. For a first app, pick three sizes: body, small body, and heading. The recommended base font size for mobile body text is 16px, sourced from both the Apple Human Interface Guidelines and Google Material Design 3, both 2024 editions. Set leading between 120% and 160% of font size for body text, and between 110% and 130% for headings. Those ranges come from Robert Bringhurst's The Elements of Typographic Style, fourth edition, 2012. Keep your measure between 45 and 75 characters per line.

Your spacing scale uses a 4px base unit with multiplicative increments. Material Design 3's 2024 spacing guidelines specify 4, 8, 12, 16, 24, 32, 48, 64, 96. Use these for margin, padding, and gap values. Do not invent a custom scale. The standard works because it gives enough granularity without infinite choice.

Component Properties That Scale

Figma components support variant, text, boolean, and instance swap property types, as documented in the Figma Help Center 2024 edition. Use variant properties for size (small, medium, large) and for visual style (primary, secondary, outline). Use boolean properties for toggling an icon or a label. Use instance swap properties for swapping an icon inside a button. Keep properties flat. A nested property tree is a sign you are over-engineering.

A design token is a named value. You store it once and reference it everywhere. This is the core principle of Material Design 3's color system and the reason your UI does not drift into inconsistency after three months of feature work.

Colour Roles From Source Values

Material Design 3 defines a source color and generates a full role set: primary, on-primary, primary container, on-primary container, secondary, on-secondary, surface, on-surface, error, on-error. For a first app, you do not need every role. You need the six listed earlier. Map each to a CSS custom property. In code, the token becomes --color-primary-default. In Figma, it becomes a local variable. Figma's variable scoping supports color, number, string, and boolean types, as of the 2024 Help Center documentation.

Set contrast ratios by specification, not by eye. WCAG 2.2 requires a 4.5:1 minimum for normal text, 3:1 for large text at or above 18px or 14px bold, and 3:1 for UI components and graphical objects. The formula is (L1 + 0.05) divided by (L2 + 0.05), where L is relative luminance in the sRGB color space. A contrast checker plugin that shows a passing ratio may be wrong. The plugin samples a rendered pixel whose antialiasing blended foreground and background, inflating the ratio by up to 1.5:1. Verify with the actual luminance calculation.

Type Scale Steps

Your type scale is a sequence of named sizes. Use three steps: body at 16px, small body at 14px, heading at 24px. Store each as a design token. Reference the token in every component. When you need a new size, add it to the scale, not to a component directly. This prevents one-off sizes that break the system.

Spacing Units

Your spacing scale uses the 4px base. Token names follow the pattern spacing 100 for 4px, spacing 200 for 8px, spacing 300 for 12px, spacing 400 for 16px, spacing 500 for 24px, spacing 600 for 32px, spacing 700 for 48px, spacing 800 for 64px, spacing 900 for 96px. Apply these to padding inside components and margin between them. Do not use arbitrary values. A button padding of 7px is a failure waiting to happen.

Documentation stops you from rebuilding the same component three times because you forgot what the first one looked like. The Nielsen Norman Group Design Systems 101 format from 2021 specifies a component name, description, variants, states, code snippet, and design asset link. Use that order.

Document Every State

For every interactive component, list the states in the same sequence every time: default, hover, active, focus, disabled, loading, empty, error. The W3C ARIA Authoring Practices Guide 1.2, 2023 edition, requires these states for accessible interactive elements. A table with one column per state is the clearest format. Fill every cell. If a state does not apply, write N/A and explain why. The before-and-after example above shows what a complete table looks like.

Accessibility Dimensions

Focus indicator requirements are specific. WCAG 2.2 Success Criterion 2.4.13 mandates a minimum thickness of 2 CSS pixels and a contrast ratio of 3:1 against adjacent colors. The touch target size for pointer inputs is 24 by 24 CSS pixels. Apple's Human Interface Guidelines, 2024 edition, recommends 44 by 44 points. Google's Material Design 3, 2024 edition, recommends 48 by 48 dp. These are not equivalent. Use the platform-specific value.

Version Control And Licensing

Version control matters even for a solo designer. Use semantic versioning. Brad Frost's Design Systems chapter on versioning, 2021, explains the MAJOR.MINOR.PATCH convention. A breaking change to a token is a major version. A new component variant is a minor version. A typo fix is a patch. Store your token JSON in a repository alongside your code. The W3C Design Tokens format is designed for this.

License your fonts correctly. A desktop license is insufficient for app embedding. You need an app or embedding license. The SIL Open Font License 1.1, from SIL International 2007, permits embedding in apps and is the safest choice for a first system. Google Fonts supplies all fonts under open licenses and is the default source for web-embeddable typefaces.

Your First Action

Open Figma. Create your token file. Define exactly 18 tokens: six colors, three type sizes, nine spacing units. Build one component. A button. Define all eight states in a documentation table. Ship that button into a screen. That is your design system. Everything else is maintenance.