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:
| Word | Reason |
|---|---|
variant | Use type - see 31.1 |
class / className | Use classes - see 31.7 |
values | Use classes - see 31.7 |
style | No inline style overrides |
body | Use 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.
| Concept | Name | Not |
|---|---|---|
| Accessible name of the component's root landmark or region | label | aria_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 icons | has_labels | is_labeled |
| Slot that holds pre-rendered media markup | media | image |
| Enum that selects which rendered shape the component ships (31.2) | type | mode, variant |
Side of its trigger a floating panel opens on: top, right, bottom, left | placement | direction |
| Id of the component's own control or root element | id | - |
| 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:
| Item | Keys |
|---|---|
| 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,maxandstepon a number or range input, andvalueandmaxon a progress bar. - A date or time bound is
prop.string, because its value is a formatted string:minandmaxon a datepicker or timepicker. autocompleteisprop.enumon a form, whose attribute takes onlyonandoff, andprop.stringon a control, whose attribute takes an autofill token list (email,shipping postal-code).
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.