{"course":{"slug":"design-foundations","title":"Design, before Any Software","url":"https://addaly.com/learn/design-foundations","level":"beginner","track":"create"},"lesson":{"slug":"naming-things","title":"Names that survive the next change","url":"https://addaly.com/learn/design-foundations/naming-things","position":67,"of":74,"minutes":8,"answer":"Name tokens and components by the role they play rather than by how they currently look, number ramps rather than labelling them small and large.","keyIdea":"Name tokens and components by the role they play rather than by how they currently look, number ramps rather than labelling them small and large, and order words from general to specific so autocomplete groups them, then test the names on somebody who did not write them."},"body":{"format":"markdown","text":"## The name outlives the value\n\n`--colour-red-error` is a token that was named twice and will be wrong once. When the error colour becomes orange because red tested badly, the name is a lie that stays in the codebase for years, and every new person has to learn that red means orange here.\n\nThe rule is straightforward and the discipline is not: **name by role, never by appearance.**\n\n```\nGood: --colour-danger        Bad: --colour-red\nGood: --colour-surface-raised Bad: --colour-light-grey\nGood: --button-primary        Bad: --button-blue\nGood: --card-interactive      Bad: --card-with-shadow\n```\n\nThe exception is the primitive layer from the previous lesson, which is *supposed* to describe values, because that is its job. `--blue-500` is a correct primitive name and an incorrect semantic one.\n\n## Numbers beat sizes\n\nFor any ramp, number the steps. Do not use light, medium and dark, because within a month you will need one between light and medium and there is no name for it.\n\n```\n--grey-50  --grey-100 --grey-200 ... --grey-900\n--space-1 --space-2 --space-3 ... --space-8\n```\n\nThe 50-to-900 convention is borrowed from font weights and has the useful property that there is always room to insert: 150 sits between 100 and 200, 250 between 200 and 300.\n\nT-shirt sizes (xs, sm, md, lg, xl) are common and have two real problems. They run out, which produces `xxxl` and then `xxxxl`. And they have no arithmetic: you cannot reason that `--space-6` is twice `--space-3`, because `lg` and `sm` do not relate.\n\nWhere t-shirt sizes work is for a small closed set that will not grow: component sizes, where small, medium and large are the whole space and always will be.\n\n## Order the words from general to specific\n\nA consistent word order makes tokens findable by typing, because an editor's autocomplete groups by prefix.\n\n```\n--colour-text-primary\n--colour-text-secondary\n--colour-text-inverse\n--colour-surface-base\n--colour-surface-raised\n--colour-border-subtle\n```\n\nType `--colour-text-` and every text colour appears. Name them the other way round, `--primary-text-colour`, and they scatter across the list alphabetically, which sounds trivial and is the difference between a system people use and one they work around.\n\nThe general pattern that most published systems converge on:\n\n```\n[category]-[element]-[role]-[state]\n\n--colour-button-primary-hover\n--space-card-inset\n--text-heading-lg\n```\n\nYou do not need every slot every time. You do need the order to be the same every time.\n\n## Naming components\n\nSame principle, one step up. A component's name should describe what it is for, not what it looks like.\n\n`Callout` survives being redesigned from a yellow box to a bordered panel. `YellowBox` does not. `Toast` and `Snackbar` are both appearance-neutral and both widely understood; `BottomPopup` describes a position that may change.\n\nThe harder version of this is naming by **role in the interface** rather than by visual treatment: `ActionBar` rather than `StickyFooter`, `FieldHint` rather than `SmallGreyText`.\n\n## The honest part: naming is hard\n\nThere is no consensus in the industry. Major published design systems disagree about almost every convention above: singular versus plural, hyphens versus dots, whether to include the category prefix, whether `background` or `surface` or `bg`. Reading three systems will give you three answers, all defensible.\n\nWhat matters far more than which convention you pick is that you pick one and apply it everywhere. A system with an idiosyncratic but consistent naming scheme is usable. A system that follows best practice in three places and something else in a fourth is not.\n\n## Naming things that come in pairs\n\nOne recurring difficulty deserves a concrete answer. A colour used as a background needs a partner colour for the text that sits on it, and the pair has to stay together or somebody will put dark text on a dark action colour.\n\nThe convention that works is an `on-` prefix, borrowed from Material Design and now widespread:\n\n```\n--colour-action      the surface\n--colour-on-action   the text and icons that sit on it\n--colour-danger\n--colour-on-danger\n```\n\nThe name states the relationship, so the pairing survives being copied into a component by somebody who was not thinking about contrast. This is a small convention that prevents one of the most common accessibility regressions, which is a themed background whose foreground was never updated with it.\n\n## Do not encode the value in the name\n\nA related trap: `--space-16` meaning sixteen pixels. It reads as helpful and it makes the value impossible to change, because a token called `--space-16` set to 20px is a lie, and everybody who reads the name will assume 16.\n\nNumber the **position on the scale**, not the value at that position. `--space-3` can be 16px today and 18px after a density review, and every name remains true.\n\nThe same applies to type: `--text-lg` survives a change; `--text-20` does not.\n\n## The test that actually works\n\nAsk somebody who did not build the system to find the right token for a task. Give them a concrete job (the colour for a destructive button's hover state, the space between a label and its input) and watch.\n\nIf they find it on the first attempt, the names work. If they have to open the file and read the whole list, the names do not, and the fix is usually word order or a missing category prefix rather than the individual names.\n\nDo this once, early, with three people. Renaming tokens later is expensive because every usage moves, so the twenty minutes spent testing names before they spread is the best-value twenty minutes in the whole exercise."},"check":{"question":"A team names its tokens --primary-text-colour, --secondary-text-colour and --raised-surface-colour. New designers repeatedly fail to find the right token and end up hard-coding values. What is the most likely cause?","options":[{"text":"The names describe roles rather than values, so a designer choosing a colour visually has no way to tell which token produces the shade they want.","correct":false,"tempting":"Argues against role naming itself, which is the convention that makes tokens survive change, and misses the findability problem."},{"text":"The word order puts the specific part first, so related tokens scatter alphabetically instead of grouping under a shared prefix.","correct":true},{"text":"The token set is missing a primitive layer, so there is nothing for designers to fall back on when no semantic token fits their case.","correct":false,"tempting":"Identifies a real structural gap that would cause designers to reference primitives rather than to hard-code arbitrary values."},{"text":"British and American spellings of colour are both in use across the system, so autocomplete matches only half the set on any given search.","correct":false,"tempting":"Names a genuine consistency hazard that the given examples do not actually exhibit."}]},"prev":{"slug":"tokens-are-decisions-with-names","title":"A token is a decision with a name","url":"https://addaly.com/learn/design-foundations/tokens-are-decisions-with-names"},"next":{"slug":"components-and-variants","title":"Variant, or a new thing","url":"https://addaly.com/learn/design-foundations/components-and-variants"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Source and assessment review continues. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'Names that survive the next change', in Design, before Any Software. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/design-foundations/naming-things (Accessed: 21 November 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"Names that survive the next change","courseTitle":"Design, before Any Software","module":{"index":7,"slug":"making-decisions-once","title":"Making the decision once"},"answer":null,"keyIdea":"Name tokens and components by the role they play rather than by how they currently look, number ramps rather than labelling them small and large, and order words from general to specific so autocomplete groups them, then test the names on somebody who did not write them.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"the-name-outlives-the-value","runs":[{"text":"The name outlives the value"}]},{"t":"p","runs":[{"text":"--colour-red-error","code":true},{"text":" is a token that was named twice and will be wrong once. When the error colour becomes orange because red tested badly, the name is a lie that stays in the codebase for years, and every new person has to learn that red means orange here."}]},{"t":"p","runs":[{"text":"The rule is straightforward and the discipline is not: "},{"text":"name by role, never by appearance.","b":true}]},{"t":"code","lang":"","label":"Text","text":"Good: --colour-danger        Bad: --colour-red\nGood: --colour-surface-raised Bad: --colour-light-grey\nGood: --button-primary        Bad: --button-blue\nGood: --card-interactive      Bad: --card-with-shadow"},{"t":"p","runs":[{"text":"The exception is the primitive layer from the previous lesson, which is "},{"text":"supposed","i":true},{"text":" to describe values, because that is its job. "},{"text":"--blue-500","code":true},{"text":" is a correct primitive name and an incorrect semantic one."}]},{"t":"h2","id":"numbers-beat-sizes","runs":[{"text":"Numbers beat sizes"}]},{"t":"p","runs":[{"text":"For any ramp, number the steps. Do not use light, medium and dark, because within a month you will need one between light and medium and there is no name for it."}]},{"t":"code","lang":"","label":"Text","text":"--grey-50  --grey-100 --grey-200 ... --grey-900\n--space-1 --space-2 --space-3 ... --space-8"},{"t":"p","runs":[{"text":"The 50-to-900 convention is borrowed from font weights and has the useful property that there is always room to insert: 150 sits between 100 and 200, 250 between 200 and 300."}]},{"t":"p","runs":[{"text":"T-shirt sizes (xs, sm, md, lg, xl) are common and have two real problems. They run out, which produces "},{"text":"xxxl","code":true},{"text":" and then "},{"text":"xxxxl","code":true},{"text":". And they have no arithmetic: you cannot reason that "},{"text":"--space-6","code":true},{"text":" is twice "},{"text":"--space-3","code":true},{"text":", because "},{"text":"lg","code":true},{"text":" and "},{"text":"sm","code":true},{"text":" do not relate."}]},{"t":"p","runs":[{"text":"Where t-shirt sizes work is for a small closed set that will not grow: component sizes, where small, medium and large are the whole space and always will be."}]},{"t":"h2","id":"order-the-words-from-general-to-specific","runs":[{"text":"Order the words from general to specific"}]},{"t":"p","runs":[{"text":"A consistent word order makes tokens findable by typing, because an editor’s autocomplete groups by prefix."}]},{"t":"code","lang":"","label":"Text","text":"--colour-text-primary\n--colour-text-secondary\n--colour-text-inverse\n--colour-surface-base\n--colour-surface-raised\n--colour-border-subtle"},{"t":"p","runs":[{"text":"Type "},{"text":"--colour-text-","code":true},{"text":" and every text colour appears. Name them the other way round, "},{"text":"--primary-text-colour","code":true},{"text":", and they scatter across the list alphabetically, which sounds trivial and is the difference between a system people use and one they work around."}]},{"t":"p","runs":[{"text":"The general pattern that most published systems converge on:"}]},{"t":"code","lang":"","label":"Text","text":"[category]-[element]-[role]-[state]\n\n--colour-button-primary-hover\n--space-card-inset\n--text-heading-lg"},{"t":"p","runs":[{"text":"You do not need every slot every time. You do need the order to be the same every time."}]},{"t":"h2","id":"naming-components","runs":[{"text":"Naming components"}]},{"t":"p","runs":[{"text":"Same principle, one step up. A component’s name should describe what it is for, not what it looks like."}]},{"t":"p","runs":[{"text":"Callout","code":true},{"text":" survives being redesigned from a yellow box to a bordered panel. "},{"text":"YellowBox","code":true},{"text":" does not. "},{"text":"Toast","code":true},{"text":" and "},{"text":"Snackbar","code":true},{"text":" are both appearance-neutral and both widely understood; "},{"text":"BottomPopup","code":true},{"text":" describes a position that may change."}]},{"t":"p","runs":[{"text":"The harder version of this is naming by "},{"text":"role in the interface","b":true},{"text":" rather than by visual treatment: "},{"text":"ActionBar","code":true},{"text":" rather than "},{"text":"StickyFooter","code":true},{"text":", "},{"text":"FieldHint","code":true},{"text":" rather than "},{"text":"SmallGreyText","code":true},{"text":"."}]},{"t":"h2","id":"the-honest-part-naming-is-hard","runs":[{"text":"The honest part: naming is hard"}]},{"t":"p","runs":[{"text":"There is no consensus in the industry. Major published design systems disagree about almost every convention above: singular versus plural, hyphens versus dots, whether to include the category prefix, whether "},{"text":"background","code":true},{"text":" or "},{"text":"surface","code":true},{"text":" or "},{"text":"bg","code":true},{"text":". Reading three systems will give you three answers, all defensible."}]},{"t":"p","runs":[{"text":"What matters far more than which convention you pick is that you pick one and apply it everywhere. A system with an idiosyncratic but consistent naming scheme is usable. A system that follows best practice in three places and something else in a fourth is not."}]},{"t":"h2","id":"naming-things-that-come-in-pairs","runs":[{"text":"Naming things that come in pairs"}]},{"t":"p","runs":[{"text":"One recurring difficulty deserves a concrete answer. A colour used as a background needs a partner colour for the text that sits on it, and the pair has to stay together or somebody will put dark text on a dark action colour."}]},{"t":"p","runs":[{"text":"The convention that works is an "},{"text":"on-","code":true},{"text":" prefix, borrowed from Material Design and now widespread:"}]},{"t":"code","lang":"","label":"Text","text":"--colour-action      the surface\n--colour-on-action   the text and icons that sit on it\n--colour-danger\n--colour-on-danger"},{"t":"p","runs":[{"text":"The name states the relationship, so the pairing survives being copied into a component by somebody who was not thinking about contrast. This is a small convention that prevents one of the most common accessibility regressions, which is a themed background whose foreground was never updated with it."}]},{"t":"h2","id":"do-not-encode-the-value-in-the-name","runs":[{"text":"Do not encode the value in the name"}]},{"t":"p","runs":[{"text":"A related trap: "},{"text":"--space-16","code":true},{"text":" meaning sixteen pixels. It reads as helpful and it makes the value impossible to change, because a token called "},{"text":"--space-16","code":true},{"text":" set to 20px is a lie, and everybody who reads the name will assume 16."}]},{"t":"p","runs":[{"text":"Number the "},{"text":"position on the scale","b":true},{"text":", not the value at that position. "},{"text":"--space-3","code":true},{"text":" can be 16px today and 18px after a density review, and every name remains true."}]},{"t":"p","runs":[{"text":"The same applies to type: "},{"text":"--text-lg","code":true},{"text":" survives a change; "},{"text":"--text-20","code":true},{"text":" does not."}]},{"t":"h2","id":"the-test-that-actually-works","runs":[{"text":"The test that actually works"}]},{"t":"p","runs":[{"text":"Ask somebody who did not build the system to find the right token for a task. Give them a concrete job (the colour for a destructive button’s hover state, the space between a label and its input) and watch."}]},{"t":"p","runs":[{"text":"If they find it on the first attempt, the names work. If they have to open the file and read the whole list, the names do not, and the fix is usually word order or a missing category prefix rather than the individual names."}]},{"t":"p","runs":[{"text":"Do this once, early, with three people. Renaming tokens later is expensive because every usage moves, so the twenty minutes spent testing names before they spread is the best-value twenty minutes in the whole exercise."}]}],"check":{"question":[{"text":"A team names its tokens --primary-text-colour, --secondary-text-colour and --raised-surface-colour. New designers repeatedly fail to find the right token and end up hard-coding values. What is the most likely cause?"}],"options":[{"text":[{"text":"The names describe roles rather than values, so a designer choosing a colour visually has no way to tell which token produces the shade they want."}],"correct":false,"tempting":[{"text":"Argues against role naming itself, which is the convention that makes tokens survive change, and misses the findability problem."}]},{"text":[{"text":"The word order puts the specific part first, so related tokens scatter alphabetically instead of grouping under a shared prefix."}],"correct":true,"tempting":null},{"text":[{"text":"The token set is missing a primitive layer, so there is nothing for designers to fall back on when no semantic token fits their case."}],"correct":false,"tempting":[{"text":"Identifies a real structural gap that would cause designers to reference primitives rather than to hard-code arbitrary values."}]},{"text":[{"text":"British and American spellings of colour are both in use across the system, so autocomplete matches only half the set on any given search."}],"correct":false,"tempting":[{"text":"Names a genuine consistency hazard that the given examples do not actually exhibit."}]}],"order":[2,1,0,3],"why":null},"prev":{"slug":"tokens-are-decisions-with-names","title":"A token is a decision with a name","minutes":8},"next":{"slug":"components-and-variants","title":"Variant, or a new thing","minutes":9}}}