# 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.

From "Design systems", a free course by Venkat R. Murty: https://designervenkat.online/learn/design-systems/code-style

## 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.

- **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.

## Why does a shared code style matter?

A design system is used by many teams, and many contributors add to it. Without shared rules, each person brings their own habits. One person names a setting 'colour' and another names it 'color'. One uses fixed colors and another uses named tokens. The product then feels patched together, and people who use the parts must learn each one again.

- **Consistency:** Every component uses the same names and patterns, so a button and a tooltip feel like relatives from one family.
- **Readability:** A new contributor can open any component and find the same layout, which makes the code faster to understand.
- **Easier reviews:** Reviewers spend their time on design choices instead of on spacing, quote marks, or how a name is spelled.
- **Fewer bugs:** When everyone follows one pattern, a mistake stands out because it breaks the pattern, so it is easier to catch.

### 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.

## Worked Example: A Button Component

Imagine a team building a Button for its design system. The team wants the button to look the same in every product, and it wants one clear way to change its look. The team follows the approach of systems such as GitHub's Primer, which publishes its token naming and linting rules.

1. **Name the props plainly:** The Button uses props named variant, size, and disabled. Variant picks the role, such as primary or secondary. Size picks one of the agreed size names. Disabled turns the button off. The Figma component and the coded component use these same names.
2. **Style with token names:** The primary variant reads a purpose-based token such as color-action-primary. It does not contain a raw hex color code. If the brand color changes, only the token's value changes.
3. **Keep the button's own tokens focused:** Tokens that belong only to the button stay with the button. Other components should not borrow them, so each part stays easy to change.
4. **Let the linter check the change:** A contributor opens a pull request that adds a prop named colour and a raw hex color. The linter flags both lines, because the rules require the agreed prop name and a token.
5. **Fix and merge:** The contributor renames the prop to variant and swaps the raw color for a token. The checks pass, and a teammate can merge the change.

> **Tip:** The team decided the rules once, in writing. The tools repeat those rules on every change, so the team never has to argue about the same Button detail twice.

**Quick check:** Two contributors add a new Tooltip. Contributor 1 names a prop 'colour' and hard-codes a dark gray hex color as the background. Contributor 2 uses a prop named 'variant' and reads a design token for the background. Which approach follows good code style, and what tool could catch the other one automatically?

A. Contributor 1, because a hard-coded color is easier for anyone to read
B. Contributor 2, and a CSS linter such as Stylelint could flag the raw color in Contributor 1's file
C. Both are fine, because a formatter such as Prettier fixes names and color choices
D. Contributor 2, but only a designer's manual review can notice the raw color

**Answer:** B. Contributor 2 follows the shared pattern: a standard prop name and a token instead of a fixed value. A formatter like Prettier only tidies layout, so it cannot fix names or colors. A linter with the right rules can flag raw values and the wrong prop name before the change merges.

### 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?

A. Leave both names, since each file works on its own
B. Rename the short names to the agreed form and add a check that flags any new short name
C. Add a new prop called size2 so that both names are accepted
D. Remove the size prop and set a fixed pixel value in every file

**Answer:** B. A convention only works when everyone uses the same form. Fixing the old names and letting a check catch future ones keeps the rule alive without a debate in every review.

## 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?

A. The name is too short for a quick read, so people will miss it
B. The name mixes a state with a raw color shade, so the shade can no longer be reused cleanly
C. Hover tokens must always be written as hex codes
D. Nothing is wrong, because names with a color shade are always the best choice

**Answer:** B. Raw shades should stay free of states and purposes so they can be reused. The state belongs in a purpose-based token that points to the shade, not inside the shade's own name.

## 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)](https://primer.style/product/primitives/token-names/)
- [Linting, Primer React documentation](https://primer.style/product/getting-started/react/linting/)
- [Primer Design Tokens Master Guide (GitHub primitives repository)](https://github.com/primer/primitives/blob/main/DESIGN_TOKENS_GUIDE.md)
- [Naming, Nord Design System](https://nordhealth.design/naming/)
- [Naming, Duet Design System](https://www.duetds.com/naming/)
- [Component naming conventions that work in Figma and code, Pegasus Design System blog](https://www.pegasusdesignsystem.com/blog/component-naming-conventions)
- [What are design tokens? A practical reference for 2026, Pegasus Design System blog](https://www.pegasusdesignsystem.com/blog/what-are-design-tokens)
- [Design Tokens and Theming Architecture, Sujeet Jaiswal](https://sujeet.pro/articles/design-tokens-and-theming)
- [Design System Token Fundamentals and Naming Conventions, CSS Architecture](https://www.css-architecture.com/design-system-token-fundamentals-naming-conventions/)
- [How to Build a Design System: A Step-by-Step Guide, Wolfpixel](https://www.wolfpixel.agency/blogs/how-to-build-a-design-system)
- [Design Tokens: How Real Design Systems Stay Consistent, Brainy](https://brainy.ink/paper/design-tokens)
- [Design Tokens: Build and Scale Systems, Tim Graf](https://timgraf.com/ux-design/design-tokens-demystified-a-complete-guide-to-building-and-scaling-design-token-systems-for-modern-product-teams/)
- [Design System Naming Conventions, UXPin](https://www.uxpin.com/studio/blog/design-system-naming-conventions/)
- [Improving code quality in React with ESLint, Prettier and TypeScript, Globant (Medium)](https://medium.com/globant/improving-code-quality-in-react-with-eslint-prettier-and-typescript-86635033d803)
- [Prettier and ESLint: Automating Code Style and Quality (Medium)](https://tianyaschool.medium.com/prettier-and-eslint-automating-code-style-and-quality-49cca1e2433c)
- [How To Integrate Prettier With ESLint And Stylelint, ExpertBeacon](https://expertbeacon.com/how-to-integrate-prettier-with-eslint-and-stylelint/)
- [ESLint and Prettier setup for React and Next.js, Workspace.hr](https://workspace.hr/blog/how-to-set-up-eslint-and-prettier-in-react-and-nextjs-projects)
- [Keep Your React Code Clean: ESLint, Prettier, Stylelint and Husky Setup (Medium)](https://medium.com/@nusratovjahongir/react-typescript-scss-eslint-prettier-stylelint-lint-staged-and-husky-57361353a394)
- [Angular ESLint and Stylelint: Linting Templates, TS, and Styles, ResumeLens](https://www.resumelens.org/blog/angular/angular-eslint-and-stylelint)
- [Improving frontend code quality, Marc Wieland](https://marcwieland.name/improving-frontend-code-quality/)
- [Design Tokens, The Design System Guide](https://thedesignsystem.guide/design-tokens)
