{"course":{"slug":"design-foundations","title":"Design, before Any Software","url":"https://addaly.com/learn/design-foundations","level":"beginner","track":"create"},"lesson":{"slug":"components-and-variants","title":"Variant, or a new thing","url":"https://addaly.com/learn/design-foundations/components-and-variants","position":68,"of":74,"minutes":9,"answer":"Make a variant when the structure and purpose are the same and only the appearance differs, and a new component when the content model differs; then define axes and rules rather than drawing permutations.","keyIdea":"Make a variant when the structure and purpose are the same and only the appearance differs, and a new component when the content model differs; then define axes and rules rather than drawing permutations, and use slots to keep the property count from doubling."},"body":{"format":"markdown","text":"## The question that comes up every week\n\nSomebody needs a button that is smaller, has an icon, sits on a dark background and is used for a destructive action. Is that a variant of the existing button, or a new component?\n\nGetting this wrong in one direction produces a library of ninety components that are all nearly the same. Getting it wrong in the other produces one component with forty properties that nobody can use correctly.\n\nThe test that resolves most cases:\n\n> **Same structure and same purpose, different appearance or emphasis → variant.**\n>\n> **Different structure or different content model → new component.**\n\nA small destructive button has the same structure as a large primary one (a container, an optional leading icon, a label) and the same purpose, which is to trigger an action. Variant.\n\nA card that contains an image, a title and three metadata rows has a different content model from a card that contains a paragraph and a link. Those are two components, even though both are rectangles with padding.\n\n## Axes, not permutations\n\nA button with 4 appearance variants, 3 sizes, 8 states and an optional icon has 4 × 3 × 8 × 2 = 192 combinations. You cannot draw 192 buttons, and you should not try.\n\nWhat you define instead is the **axes** and the **rules for each axis**:\n\n> Figure: A variant, or a new component. A variant: Same structure, same purpose; A small destructive button beside a large primary one; Defined as one more value on an axis; Costs a row in the documentation. A new component: Different structure or content model; A card of image, title and metadata against a card of paragraph and link; Needs its own anatomy and its own states; Costs an entry in the library, for as long as it lives. Four appearances, three sizes, eight states and an optional icon is 192 combinations. Define the axes and the rules, and draw only the ones that change the structure.\n\n```\nvariant:  primary | secondary | ghost | danger\nsize:     sm (32px) | md (40px) | lg (48px)\nstate:    default | hover | focus | active | disabled | loading\nicon:     none | leading | trailing | icon-only\n```\n\nThen document how each axis behaves independently, and draw only the combinations that are non-obvious: usually icon-only, disabled, and loading, because those change the structure rather than just the colour.\n\nThis is also the argument for keeping the axis count low. Every new boolean property doubles the space. A component with nine boolean properties has 512 configurations, most of which nobody has ever looked at, and several of which are certainly broken.\n\n## Slots keep the count down\n\nThe technique that prevents most component sprawl: give a component a **slot** (a region that accepts arbitrary content) rather than a property for every possible piece of content.\n\nA card with a `header` slot, a `body` slot and a `footer` slot serves fifty layouts. A card with `title`, `subtitle`, `imageUrl`, `badgeText`, `badgeColour`, `metaLine1`, `metaLine2`, `ctaLabel` and `ctaHref` serves exactly one, and the next requirement adds a tenth property.\n\nThe trade-off is real: slots give up control, so a card with a free body slot can contain something that looks wrong. The usual resolution is slots for layout regions and properties for the things the system wants to govern, such as the card's own padding and elevation.\n\n## Anatomy: name the parts\n\nFor every component, name its parts. This sounds like bureaucracy and it is what makes the conversations possible.\n\n```\nButton anatomy:  container · leading icon · label · trailing icon · focus ring\nField anatomy:   label · control · hint · error message · required marker\nCard anatomy:    surface · media · header · body · footer\n```\n\nWith names, a review comment can be the gap between the leading icon and the label is 4px and should be 8. Without them it is the icon thing looks squashed, which produces a different fix each time.\n\n## Signs a component should be split\n\n- It has a property that changes several other properties' meanings.\n- Half its properties are only valid when another property has a particular value.\n- People keep detaching or copying it instead of using it.\n- Its documentation needs the word except.\n- Its name contains and.\n\nThat last one is reliable enough to be a rule of thumb. `SearchAndFilterBar` is two components.\n\n## Signs it should not have been split\n\nThe opposite failure is just as common and harder to see, because a large library feels like progress.\n\n- Two components with the same anatomy and different colours.\n- A component used exactly once, ever.\n- Three components that were copied from each other and have since drifted.\n\nThe audit: list every component and its usage count. The ones used once are candidates for deletion or for merging back into whatever they were copied from. A library where a third of the entries are used once is not a system; it is a folder."},"check":{"question":"A card component has accumulated properties: title, subtitle, imageUrl, badgeText, badgeColour, metaLine1, metaLine2, ctaLabel and ctaHref. A new design needs a card with a chart in place of the image. What is the better response?","options":[{"text":"Add a chartData property alongside imageUrl, with a rule that exactly one of the two must be supplied.","correct":false,"tempting":"Adds a property whose validity depends on another property's value, which is one of the signs a component has outgrown its shape."},{"text":"Create a ChartCard component, so each card type has a property set matched to its own content.","correct":false,"tempting":"Splits into components with identical anatomy and different content slots, which produces the duplication the split was meant to avoid."},{"text":"Replace the content properties with a media slot and a body slot that accept arbitrary content.","correct":true},{"text":"Keep imageUrl and render the chart to an image server-side, so the existing component continues to work without modification.","correct":false,"tempting":"Preserves the interface by degrading the content into a raster image, losing interactivity and accessibility to avoid a structural change."}]},"prev":{"slug":"naming-things","title":"Names that survive the next change","url":"https://addaly.com/learn/design-foundations/naming-things"},"next":{"slug":"states-are-part-of-the-component","title":"Every state you did not draw still ships","url":"https://addaly.com/learn/design-foundations/states-are-part-of-the-component"},"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) 'Variant, or a new thing', in Design, before Any Software. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/design-foundations/components-and-variants (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":"Variant, or a new thing","courseTitle":"Design, before Any Software","module":{"index":7,"slug":"making-decisions-once","title":"Making the decision once"},"answer":null,"keyIdea":"Make a variant when the structure and purpose are the same and only the appearance differs, and a new component when the content model differs; then define axes and rules rather than drawing permutations, and use slots to keep the property count from doubling.","hero":{"kind":"figure","figure":{"t":"figure","label":"Figure","figure":{"caption":"Four appearances, three sizes, eight states and an optional icon is 192 combinations. Define the axes and the rules, and draw only the ones that change the structure.","left":{"title":"A variant","items":["Same structure, same purpose","A small destructive button beside a large primary one","Defined as one more value on an axis","Costs a row in the documentation"]},"right":{"title":"A new component","items":["Different structure or content model","A card of image, title and metadata against a card of paragraph and link","Needs its own anatomy and its own states","Costs an entry in the library, for as long as it lives"]},"title":"A variant, or a new component","type":"compare"},"alt":"Figure: A variant, or a new component. A variant: Same structure, same purpose; A small destructive button beside a large primary one; Defined as one more value on an axis; Costs a row in the documentation. A new component: Different structure or content model; A card of image, title and metadata against a card of paragraph and link; Needs its own anatomy and its own states; Costs an entry in the library, for as long as it lives. Four appearances, three sizes, eight states and an optional icon is 192 combinations. Define the axes and the rules, and draw only the ones that change the structure."}},"blocks":[{"t":"h2","id":"the-question-that-comes-up-every-week","runs":[{"text":"The question that comes up every week"}]},{"t":"p","runs":[{"text":"Somebody needs a button that is smaller, has an icon, sits on a dark background and is used for a destructive action. Is that a variant of the existing button, or a new component?"}]},{"t":"p","runs":[{"text":"Getting this wrong in one direction produces a library of ninety components that are all nearly the same. Getting it wrong in the other produces one component with forty properties that nobody can use correctly."}]},{"t":"p","runs":[{"text":"The test that resolves most cases:"}]},{"t":"quote","runs":[{"text":"Same structure and same purpose, different appearance or emphasis → variant.","b":true}]},{"t":"quote","runs":[]},{"t":"quote","runs":[{"text":"Different structure or different content model → new component.","b":true}]},{"t":"p","runs":[{"text":"A small destructive button has the same structure as a large primary one (a container, an optional leading icon, a label) and the same purpose, which is to trigger an action. Variant."}]},{"t":"p","runs":[{"text":"A card that contains an image, a title and three metadata rows has a different content model from a card that contains a paragraph and a link. Those are two components, even though both are rectangles with padding."}]},{"t":"h2","id":"axes-not-permutations","runs":[{"text":"Axes, not permutations"}]},{"t":"p","runs":[{"text":"A button with 4 appearance variants, 3 sizes, 8 states and an optional icon has 4 × 3 × 8 × 2 = 192 combinations. You cannot draw 192 buttons, and you should not try."}]},{"t":"p","runs":[{"text":"What you define instead is the "},{"text":"axes","b":true},{"text":" and the "},{"text":"rules for each axis","b":true},{"text":":"}]},{"t":"code","lang":"","label":"Text","text":"variant:  primary | secondary | ghost | danger\nsize:     sm (32px) | md (40px) | lg (48px)\nstate:    default | hover | focus | active | disabled | loading\nicon:     none | leading | trailing | icon-only"},{"t":"p","runs":[{"text":"Then document how each axis behaves independently, and draw only the combinations that are non-obvious: usually icon-only, disabled, and loading, because those change the structure rather than just the colour."}]},{"t":"p","runs":[{"text":"This is also the argument for keeping the axis count low. Every new boolean property doubles the space. A component with nine boolean properties has 512 configurations, most of which nobody has ever looked at, and several of which are certainly broken."}]},{"t":"h2","id":"slots-keep-the-count-down","runs":[{"text":"Slots keep the count down"}]},{"t":"p","runs":[{"text":"The technique that prevents most component sprawl: give a component a "},{"text":"slot","b":true},{"text":" (a region that accepts arbitrary content) rather than a property for every possible piece of content."}]},{"t":"p","runs":[{"text":"A card with a "},{"text":"header","code":true},{"text":" slot, a "},{"text":"body","code":true},{"text":" slot and a "},{"text":"footer","code":true},{"text":" slot serves fifty layouts. A card with "},{"text":"title","code":true},{"text":", "},{"text":"subtitle","code":true},{"text":", "},{"text":"imageUrl","code":true},{"text":", "},{"text":"badgeText","code":true},{"text":", "},{"text":"badgeColour","code":true},{"text":", "},{"text":"metaLine1","code":true},{"text":", "},{"text":"metaLine2","code":true},{"text":", "},{"text":"ctaLabel","code":true},{"text":" and "},{"text":"ctaHref","code":true},{"text":" serves exactly one, and the next requirement adds a tenth property."}]},{"t":"p","runs":[{"text":"The trade-off is real: slots give up control, so a card with a free body slot can contain something that looks wrong. The usual resolution is slots for layout regions and properties for the things the system wants to govern, such as the card’s own padding and elevation."}]},{"t":"h2","id":"anatomy-name-the-parts","runs":[{"text":"Anatomy: name the parts"}]},{"t":"p","runs":[{"text":"For every component, name its parts. This sounds like bureaucracy and it is what makes the conversations possible."}]},{"t":"code","lang":"","label":"Text","text":"Button anatomy:  container · leading icon · label · trailing icon · focus ring\nField anatomy:   label · control · hint · error message · required marker\nCard anatomy:    surface · media · header · body · footer"},{"t":"p","runs":[{"text":"With names, a review comment can be the gap between the leading icon and the label is 4px and should be 8. Without them it is the icon thing looks squashed, which produces a different fix each time."}]},{"t":"h2","id":"signs-a-component-should-be-split","runs":[{"text":"Signs a component should be split"}]},{"t":"ul","items":[[{"text":"It has a property that changes several other properties’ meanings."}],[{"text":"Half its properties are only valid when another property has a particular value."}],[{"text":"People keep detaching or copying it instead of using it."}],[{"text":"Its documentation needs the word except."}],[{"text":"Its name contains and."}]]},{"t":"p","runs":[{"text":"That last one is reliable enough to be a rule of thumb. "},{"text":"SearchAndFilterBar","code":true},{"text":" is two components."}]},{"t":"h2","id":"signs-it-should-not-have-been-split","runs":[{"text":"Signs it should not have been split"}]},{"t":"p","runs":[{"text":"The opposite failure is just as common and harder to see, because a large library feels like progress."}]},{"t":"ul","items":[[{"text":"Two components with the same anatomy and different colours."}],[{"text":"A component used exactly once, ever."}],[{"text":"Three components that were copied from each other and have since drifted."}]]},{"t":"p","runs":[{"text":"The audit: list every component and its usage count. The ones used once are candidates for deletion or for merging back into whatever they were copied from. A library where a third of the entries are used once is not a system; it is a folder."}]}],"check":{"question":[{"text":"A card component has accumulated properties: title, subtitle, imageUrl, badgeText, badgeColour, metaLine1, metaLine2, ctaLabel and ctaHref. A new design needs a card with a chart in place of the image. What is the better response?"}],"options":[{"text":[{"text":"Add a chartData property alongside imageUrl, with a rule that exactly one of the two must be supplied."}],"correct":false,"tempting":[{"text":"Adds a property whose validity depends on another property’s value, which is one of the signs a component has outgrown its shape."}]},{"text":[{"text":"Create a ChartCard component, so each card type has a property set matched to its own content."}],"correct":false,"tempting":[{"text":"Splits into components with identical anatomy and different content slots, which produces the duplication the split was meant to avoid."}]},{"text":[{"text":"Replace the content properties with a media slot and a body slot that accept arbitrary content."}],"correct":true,"tempting":null},{"text":[{"text":"Keep imageUrl and render the chart to an image server-side, so the existing component continues to work without modification."}],"correct":false,"tempting":[{"text":"Preserves the interface by degrading the content into a raster image, losing interactivity and accessibility to avoid a structural change."}]}],"order":[3,2,1,0],"why":null},"prev":{"slug":"naming-things","title":"Names that survive the next change","minutes":8},"next":{"slug":"states-are-part-of-the-component","title":"Every state you did not draw still ships","minutes":9}}}