Code Style: Shared Rules That Make Every Component Look Like One Hand Wrote It
Code style is the agreed set of naming, file, and formatting rules behind a design system's code, enforced by tools so no one has to argue about them in reviews.
In short
Code style is the agreed set of naming, file and formatting rules behind a design system's code, enforced by tools so no one argues about them in reviews.
12 min readFree
What You Will Learn
A design system is more than pictures and rules. Much of it is code: the buttons, text fields, and colors that product teams pull in and use. Many people write that code over time. Code style is the set of agreed rules for how that code is named, arranged, and formatted. When the rules are shared, every part looks and behaves as if one careful person wrote it.
In this lesson you will learn why a shared code style matters, what a style guide usually decides, and how teams use tools to enforce the rules. The tools handle the small checks, so reviews can focus on design. You will follow one Button component from start to finish.
Key words
- Code style
- The agreed rules for how code is named, arranged, and formatted.
- Style guide
- The written document that lists a team's code style decisions.
- Component
- A reusable piece of a product, such as a button, a checkbox, or a tooltip.
- Prop
- A setting passed into a component to change it, such as its size or its style variant.
- Design token
- A named design decision, such as a brand color, stored under one name instead of as a fixed number.
- Raw value
- A fixed number or code typed straight into a component, such as a hex color code or a pixel size.
- Linter
- A tool that checks code against a set of rules and reports the places that break them.
- Formatter
- A tool that rearranges spacing, line breaks, and quote marks so the code has one look.
- Pull request
- A proposed change to shared code that teammates check before it is added.
- Merge
- To accept a proposed change into the main shared code.
One Hand, Many Contributors
Think of a design system as a shared kitchen. Many cooks prepare dishes, but the diner should not be able to tell who cooked which one. Code style does the same job for code. It hides the differences between contributors so the product looks like one team's work.
Tip
Drift is the slow gap that grows between the design and the code. Matching names in design files and in code is one of the cheapest ways to slow it down.
What does a style guide define?
A code style guide is a written document. It records the team's decisions so new people do not have to guess. Most guides for design systems cover four areas.
Naming
How components, props, CSS classes, and design tokens get their names.
File and folder structure
Where each component's files live and how related parts are grouped together.
Formatting
Spacing, indentation, line breaks, quote marks, and the order of settings inside a file.
Documentation and comments
How to describe what a component does and how to explain a choice that is not obvious.
Naming Conventions
A naming convention is one pattern used for every name of one kind. A team may write one pattern for components, another for props, another for CSS classes, and another for tokens. The rule is about consistency, not about which pattern is best.
Look at two real guides. Nord does the opposite and asks for short names such as s, m, and l. Both teams are right for their own system. What matters for a learner is that each team picks one form and uses it everywhere.
Component names should be things, not actions. Nord suggests nouns, so a name such as input or tab fits better than a verb such as animating.
Nord starts its component names with a prefix and a hyphen, because the prefix keeps its names from clashing with names in other systems.
Pegasus recommends one word for one thing everywhere. The Figma component, the coded component, its props, and the tokens it reads should all share the same names. For a Button, that means the same PascalCase name, such as Button, in both places.
How do you name tokens by purpose?
A token is a named design decision. The most useful token names say what a value is for, not what it looks like. Pegasus contrasts a name that says how a color should be used with a name that only says which shade of blue it is. In code, the same path becomes a CSS variable with dashes between the words.
This matters because a name that describes looks can become wrong. If a token is called blue-500 and the brand later changes its color, the name no longer fits. A purpose-based name such as color-action-primary still makes sense after the value changes.
Primer, GitHub's design system, follows a token naming convention so people can tell at a glance what a token does and how it should be used.
Good teams keep the mode out of the name. A name such as text-primary-dark is a second token pretending to be a mode. Light and dark themes should share one name and receive different values.
Tip
Try a simple test. If someone reads only the token name, do they know when to use it? If not, the name is probably describing the look instead of the purpose.
File and Folder Structure
Files should be easy to find without searching. Many teams give each component its own folder and keep its code, its styling, and its notes together. A reader can then open one folder and see the whole part.
Teams also decide where shared tokens live. Global tokens usually sit in one common place, while tokens that belong to one component stay close to that component. One CSS architecture guide follows this split and warns against making a new token for every small variation.
Formatting and Comments
Formatting covers spacing, indentation, line length, quote marks, and the order of settings inside a style block. The goal is not to find the perfect layout. The goal is that every file looks the same, so a reader's eye always knows where to look.
Some teams also set an order for CSS properties.
Comments should explain why a choice was made, not repeat what the code does. A short note that says why a focus outline must stay visible is far more useful to the next person than a note that just names the setting.
How is style enforced?
A written guide is not enough on its own. People forget rules, and reviewers get tired. So teams let tools check the rules automatically. The tools do the repeated work, and the team only argues about rules that are truly new or unclear.
What are linters and formatters?
ESLint
A linter for script code. It finds common problems and enforces the rules a team agrees on.
Prettier
A formatter. It rewrites spacing, indentation, and line breaks so every file has the same look.
Stylelint
A linter for stylesheets, the CSS that sets colors, spacing, and sizes. It helps enforce consistent CSS conventions.
These tools work as a pair. The formatter handles the look of the code, and the linter handles the rules. That way the two tools never disagree about where a line break belongs.
Linters can also check design-specific rules. Primer ships an ESLint plugin that enforces best practices and fixes common problems in its React components.
Editor Settings
Editor settings are preferences saved with a project. They make every contributor's code editor follow the same formatting and checks. Teams often install the Prettier, ESLint, and Stylelint extensions in their editor and save the shared settings in the project.
When the setup is right, code is tidied as it is saved.
Automatic Checks Before a Merge
- 1
Write the change
A contributor edits a component and its tokens in their own copy of the shared code.
- 2
Run checks before saving
Editor and project tools run the formatter and linter. Some teams also check each change as it is committed.
- 3
Open a pull request
The change is proposed to the team, and the automatic checks run again on the proposed code.
- 4
Block broken changes
If a check fails, the change cannot merge until the problem is fixed. Some teams say that any new violation breaks the automatic check.
- 5
Review the design choices
People still judge what tools cannot judge, such as whether a new component is needed at all.
Tip
Start with a few rules. Add a new rule only after the team has seen the same mistake more than once, so the rules stay easy to remember.
Checking Names in Practice
Quick check
A team's Badge component takes size names 's' in one file and 'large' in another. The team's style guide asks for one agreed form. What is the best next step?
Keeping the Style Alive
A style guide goes stale when no one owns it. Teams review it on a set schedule, add examples from real components, and remove rules that nobody follows. New rules are proposed the same way as other changes, so the reasons stay visible to everyone.
Tokens need the same care. For CSS variables, that often means kebab-case, where words are joined by dashes. Teams that agree on casing early avoid translation problems later.
Renaming is the hardest change.
Own the guide
Name a person or small group who answers questions and approves new rules.
Show real examples
Keep the guide tied to real components so people see the rules in use.
Retire rules slowly
Give teams time to move away from old names before a rule is removed.
Check Yourself
Read this short scenario and pick the best answer. The answer depends on the idea of purpose-based names from this lesson.
Quick check
A contributor names a new link color token color-hover-blue-600. The shade is a raw color value, and the name also records a hover state. What problem is most likely?
Key Takeaways
Shared rules
Code style makes many contributors' code look and behave as if one person wrote it.
A written guide
The style guide covers naming, file structure, formatting, and comments.
Purpose-based names
Tokens should describe what a value is for, not how it looks.
Tools enforce the rules
Formatters, linters, and editor settings check the rules before a change merges.
Code style protects the system after the first build. When the rules are clear and the tools repeat them, a design system can grow with many contributors and still feel like one product.
Sources
- Token names, Primer product documentation (GitHub)
- Linting, Primer React documentation
- Primer Design Tokens Master Guide (GitHub primitives repository)
- Naming, Nord Design System
- Naming, Duet Design System
- Component naming conventions that work in Figma and code, Pegasus Design System blog
- What are design tokens? A practical reference for 2026, Pegasus Design System blog
- Design Tokens and Theming Architecture, Sujeet Jaiswal
- Design System Token Fundamentals and Naming Conventions, CSS Architecture
- How to Build a Design System: A Step-by-Step Guide, Wolfpixel
- Design Tokens: How Real Design Systems Stay Consistent, Brainy
- Design Tokens: Build and Scale Systems, Tim Graf
- Design System Naming Conventions, UXPin
- Improving code quality in React with ESLint, Prettier and TypeScript, Globant (Medium)
- Prettier and ESLint: Automating Code Style and Quality (Medium)
- How To Integrate Prettier With ESLint And Stylelint, ExpertBeacon
- ESLint and Prettier setup for React and Next.js, Workspace.hr
- Keep Your React Code Clean: ESLint, Prettier, Stylelint and Husky Setup (Medium)
- Angular ESLint and Stylelint: Linting Templates, TS, and Styles, ResumeLens
- Improving frontend code quality, Marc Wieland
- Design Tokens, The Design System Guide
Last updated on 17 November 2026
Related lessons
- Design systemsStyle in Design Systems: Repeatable Visual Choices That Give a Product One Look
- AI guardrails & red teamingCode injection and RCE
- Design systemsIcon: One Shared Grid, Stroke, and Component for Every Symbol
- Design systemsVisual Forms: The Shape and Depth Rules That Give Components One Family Look
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.