Skip to main content

Rule 31 - Twig: Component props

Naming conventions for Twig template props.

Rules​

31.1. variant MUST NOT be used as a prop name. Variants are composable CSS value classes (Rule 21), not a Twig prop.

31.2. type MUST be used for enum-based selection when a component ships multiple distinct rendered shapes. Every other native HTML attribute is passed via the attributes prop (see 31.8).

type is the one exception to that split. Where the component's root element carries a native type attribute over a fixed value set - <button>, <input> - the prop maps to that attribute and is declared outlier: true per Rule 53.7, because its values are HTML's rather than the capability vocabulary's.

Example: {% include 'semetrika:hero' with { type: 'featured' } %}

31.3. Boolean props MUST use descriptive prefixes that read as a statement. Even names that mirror an HTML attribute MUST carry the prefix - is_disabled, is_required, is_checked, never bare disabled/required/checked. The twig template maps the prefixed prop name back to the unprefixed HTML attribute at render time.

  • is_* - state (is_decorative, is_open, is_required, is_invalid, is_disabled, is_checked, is_readonly)

  • has_* - feature presence (has_backdrop, has_close)

  • use_* - opt-in behavior (use_cookie, use_container)

    31.4. Content slots MUST be named by purpose or position, not by number. Named slots (supertitle, content_middle) MUST be used for fixed-purpose positions. Positional slots (top1, middle1) MAY be used for generic grid slots.

    31.5. Object props MUST use structured keys matching HTML/ARIA attributes where possible:

  • Image: { url, alt }
  • Link: { url, text }
  • Breadcrumb: { links, active_is_link }
  • File: { url, name, extension, size }

31.6. Link objects MUST use url and text (not href and label).

Standard passthrough props​

31.7. Every component MUST accept a classes prop - an array of CSS class names to add to the root element. This is the mechanism for consumers to apply value classes, utility classes, or any other CSS classes from outside the template.

{% include 'semetrika:button' with {
content: 'Cancel',
classes: ['subtle', 'outline', 'sm'],
} %}
{# renders: <button class="subtle outline sm">Cancel</button> #}

31.8. Every component MUST accept an attributes prop - an object of HTML attributes to add to the root element. This is the mechanism for passing native HTML attributes (type, id, data-*, aria-*, etc.) without the template needing to enumerate each one.

{% include 'semetrika:button' with {
content: 'Submit',
attributes: { type: 'submit', id: 'launch-btn' },
} %}
{# renders: <button type="submit" id="launch-btn">Submit</button> #}

Enum validation​

31.9. Enum props (type, title_tag, or any prop accepting a fixed set of values) MUST be validated against the allowed values and MUST fall back to a default when the provided value is not in the set. The inline ternary pattern MUST be used:

{%- set type = type in ['default', 'featured'] ? type : 'default' -%}
{%- set title_tag = title_tag in ['h2', 'h3', 'h4'] ? title_tag : 'h3' -%}

31.10. The following prop names are RESERVED and MUST NOT be used for component-specific purposes:

WordReason
variantUse type - see 31.1
class / classNameUse classes - see 31.7
valuesUse classes - see 31.7
styleNo inline style overrides
bodyUse content - see 31.11

Content slot prop​

31.11. The prop name for a component's main content slot MUST be content. Synonyms such as body, html, text, children, or inner MUST NOT be used.

{# Correct #}
{% set content = content|default('') %}

{# Wrong - reserved synonyms #}
{% set body = body|default('') %}
{% set html = html|default('') %}

A single canonical name keeps consumer templates portable across components ({% include 'semetrika:modal' with { content: … } %} renders the same slot as card or callout). The ban governs the main content slot. A named part that renders its own visible text beside the main slot takes {part}_text, or text where the part is the trigger or instruction the component wraps (tooltip's text labels the trigger; exit's text is the instruction beside the button). Drift is currently caught at code review time only - no automated check enforces the content-only convention. Future codification candidate.

Forbidden prop names​

31.12. The prop name title_level MUST NOT be used. Components render their title element through the title_tag prop - an enum of tag names (strong, p, h1-h6) validated inline per Rule 31.9. The legacy title_level name, whether a numeric heading level or a tag string, is read by no component, so it silently renders the default tag. Every title element MUST be selected through title_tag with an explicit tag value. The ban is enforced across *.twig, *.spec.js, and *.stories.js under src/.

{# Wrong - title_level is read by no component, renders the default tag #}
{% include 'semetrika:card' with { title: 'Apollo 11', title_level: 3 } only %}

{# Correct - title_tag with an explicit tag #}
{% include 'semetrika:card' with { title: 'Apollo 11', title_tag: 'h3' } only %}

One name per concept​

31.13. A Component MUST name each concept below with the name the table gives it. Consumer templates pass props by name, so two components that name one concept differently make every caller learn both.

ConceptNameNot
Accessible name of the component's root landmark or regionlabelaria_label, a hard-coded string
Accessible name of a named part{part}_label (trigger_label, primary_label)aria_{part}
Flag that shows text labels beside iconshas_labelsis_labeled
Slot that holds pre-rendered media markupmediaimage
Enum that selects which rendered shape the component ships (31.2)typemode, variant
Side of its trigger a floating panel opens on: top, right, bottom, leftplacementdirection
Id of the component's own control or root elementid-
Id of one named part{part}_id (helper_id, menu_id)-
Base that several of the component's own ids derive from{component}_id (navbar_id, tabs_id)id_prefix

No prop or slot is named after an ARIA attribute. An ARIA attribute the component does not model passes through attributes (31.8).

A component reads its root's accessible name from label first and from an aria-label passed through attributes second, and uses its own default only when both are empty. The passthrough skips aria-label, so the root never carries the attribute twice.

image stays free for an { url, alt } object prop (31.5), which is structured data rather than markup.

An enum whose values combine with another enum's values on one element is not a rendered shape. It takes the name of the capability layer its values extend (Rule 53.7): table's surface and layout, and navbar's layout.

// Correct.
prop.string('label', { default: 'Carousel', description: 'Accessible name for the carousel region.' }),
prop.enum('placement', { outlier: true, asClass: false, values: ['top', 'right', 'bottom', 'left'], default: 'bottom', description: '…' }),

// Wrong - the same concepts under other names.
prop.string('aria_label', { default: 'Carousel', description: 'Accessible label for the carousel region.' }),
prop.enum('direction', { values: ['opens-down', 'opens-up'], default: 'opens-down', description: '…' }),

Item objects​

31.14. An object inside an array or object prop MUST take its keys from what the item is:

ItemKeys
Link{ url, text } (31.6)
Heading with a body{ title, content }
File{ url, name, extension, size } (31.5)
Select option{ text, value }

A boolean key on an item MUST carry a 31.3 prefix, the same as a prop: is_current, is_disabled, is_selected, is_open. The template reads the prefixed key and renders the unprefixed attribute.

{# Correct #}
<option value="{{ option.value }}"{{ option.is_selected ? ' selected' : '' }}>{{- option.text -}}</option>

{# Wrong - a bare boolean key #}
<option value="{{ option.value }}"{{ option.selected ? ' selected' : '' }}>{{- option.text -}}</option>

Scalar prop types​

31.15. A scalar prop's type MUST follow the value space of the attribute it renders.

  • A numeric attribute on a numeric control is prop.number: value, min, max and step on a number or range input, and value and max on a progress bar.
  • A date or time bound is prop.string, because its value is a formatted string: min and max on a datepicker or timepicker.
  • autocomplete is prop.enum on a form, whose attribute takes only on and off, and prop.string on a control, whose attribute takes an autofill token list (email, shipping postal-code).

Enforced by

31.3, 31.12, 31.13, 31.14 by yarn cli 31 (findInvalidBooleanPropNames, findForbiddenTitleLevel, findNonCanonicalPropNames, findUnprefixedItemFlags in packages/cli/src/rules/31.js). 31.1, 31.2, 31.4-31.11, 31.15 are review only. See enforcement.md.