---
title: "Prefix a component's custom properties · Agent Wranglers"
url: https://agentwranglers.se/playbook/html-css/naming-and-state/component-custom-properties
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Prefix a component's custom properties with its name

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

For AI agents: [llms.txt](https://agentwranglers.se/llms.txt) is a short guide that sends you to the rules your problem needs, and [rules.json](https://agentwranglers.se/playbook/html-css/rules.json) holds every rule of this playbook as JSON.

- Level: Recommended
- Chapter: [Naming and state](https://agentwranglers.se/playbook/html-css/naming-and-state)
- Rule: Name every custom property defined in a component file with the module prefix, such as `--order-card-gap`. Set it from a global token, and let variants change only these local properties.
- How: Global tokens hold the project's values, as [Take every style value from design tokens](https://agentwranglers.se/playbook/app-ui/styles-and-components/design-tokens) describes. A component maps them to its own properties once at its root. Variants then change one local property instead of repeating whole declarations. A component never redefines a global token, so a change inside one module cannot leak into the rest of the page. Colour tokens follow [Define every colour once](https://agentwranglers.se/playbook/website/interface/colour-as-tokens).
- Check: Every custom property declared in a component file starts with `--` followed by that file's prefix. Component files declare 0 global token names.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### CSS example

```css
/* components/order-card.css */
.order-card {
  --order-card-gap: var(--space-small);
  gap: var(--order-card-gap);
}
.order-card[data-size="large"] { --order-card-gap: var(--space-large); }

/* Fails: redefines a global token inside a component */
.order-card { --space-small: 2px; }
```

### HTML example

```html
<article class="order-card" data-size="large">Wedding cake, three tiers</article>
```

## Sources

- [CSS Custom Properties Level 1](https://www.w3.org/TR/css-variables-1/#defining-variables)

## Related rules

- [Take every style value from design tokens](https://agentwranglers.se/playbook/app-ui/styles-and-components/design-tokens) in App interface
- [Define every colour once](https://agentwranglers.se/playbook/website/interface/colour-as-tokens) in Website

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/html-css/naming-and-state/component-custom-properties">Agent Wranglers HTML and CSS playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Never style by position or deep nesting](https://agentwranglers.se/playbook/html-css/naming-and-state/no-position-selectors)
- Next: [Keep script hooks apart from style hooks](https://agentwranglers.se/playbook/html-css/naming-and-state/separate-script-hooks)
- [Naming and state](https://agentwranglers.se/playbook/html-css/naming-and-state)