{ "componentChunkName": "component---src-templates-handbook-tsx", "path": "/handbook/nuts/components", "result": {"data":{"markdownRemark":{"html":"

The UI is built by composing components. Pages do not have their own stylesheets — all styling lives in the components they compose. In a React app a page component owns both data fetching and UI composition, so the two responsibilities live together in one file. In a Rails full-stack app the split is clearer: data handling belongs in the controller and the view component is purely about composing presentational components.

\n

Working on components means close collaboration with designers and Figma. Before implementing anything, the first place to check is the shaping section of the GitHub issue — it will tell you what components are expected and whether they are new or already exist. Components are named in code the same way they are named in Figma, so the design file is a reliable indicator of whether a component has already been implemented. If the project has Storybook set up, that is another quick way to browse what is already available before writing anything new.

\n

Once a feature is implemented, test it across different browsers and operating systems before marking it done. Visual bugs that only appear on specific platforms are common and easy to catch early with a quick cross-browser check.

\n

Presentational (Dumb) Components

\n

Presentational components own their markup and styling. They receive all their data through props, make no API calls, and hold no application state — they are only responsible for how things look.

\n

When building a component or page, reach for these primitives first and compose them together. If a layout or styling requirement cannot be met with the available primitives, check whether a new primitive is warranted before adding ad hoc markup. The rule of three applies: only extract a new primitive once the same pattern has appeared independently in at least three places. A one-off layout belongs in the component that needs it, not in shimmer-components.

\n

File Structure

\n

Each component lives in its own folder under src/components, containing exactly two files: the component itself and its stylesheet.

\n
src/components/document_card/document_card.tsx\nsrc/components/document_card/document_card.scss\n
\n

The folder name, file names, and BEM block in the stylesheet must all match. The component identifier in code uses PascalCase (DocumentCard) while the file and folder use snake_case.

\n

When a component needs to be targeted by JavaScript (e.g. for event delegation or test selectors), use data- attributes rather than IDs or class names. Name them after the role, not the implementation: data-action=\"submit\" rather than data-button=\"true\". Never use BEM class names as JS hooks — classes are for styling only.

\n

Primitives

\n

Every project ships the same set of low-level layout and typography components. These primitives are provided by the shimmer-components library and should be the first thing you reach for when composing any component or page. Do not re-implement layout patterns from scratch — use these instead.

\n

If a primitive you need does not exist in shimmer-components, implement it according to the correct Figma design in the project before using it. Do not add ad hoc markup as a substitute for a missing primitive.

\n
\n

Note: Grid and Icon are not yet part of shimmer-components. Copy the implementation from an existing project — ask a senior developer for the recommended source.

\n
\n

Grid

\n

Use Grid whenever you need to arrange content in a two-dimensional layout. Define column, row, and gap settings per breakpoint using the mobile, tablet, desktop, and desktopLg props.

\n
<Grid\n  mobile={{ gap: 8 }}\n  desktop={{ columns: 'repeat(2, 1fr)' }}\n  desktopLg={{ gap: 16 }}\n>\n  <Card />\n  <Card />\n</Grid>\n
\n
# Phlex — grid applies layout via CSS custom properties\ngrid(\n  mobile: { gap: 8 },\n  desktop: { columns: \"repeat(2, 1fr)\" },\n  desktop_lg: { gap: 16 }\n) do\n  # child components\nend\n
\n

Prefer Grid over recreating grid layout with custom CSS in a component's stylesheet. Custom grid layouts are sometimes necessary, but reach for Grid first.

\n

Icon

\n

Use Icon to render an SVG icon by name. Always pass a size prop in pixels. Icon is purely presentational — it is never interactive on its own. Buttons that display an icon use a Button or IconButton component that wraps Icon.

\n
<Icon name=\"arrow-new-tab\" size={16} />\n
\n
# Phlex\nicon(name: \"arrow-new-tab\", size: 16)\n
\n

Stack

\n

Use Stack whenever you need to lay out a series of elements in a single direction. The default direction is vertical. Add the line prop for a horizontal row. Pass gap, align, and justify to control spacing and alignment.

\n
{\n  /* Horizontal row with space between and centered alignment */\n}\n<Stack gap={0} line justify=\"space-between\" align=\"center\">\n  <Text type=\"caption-bold\">{i18n.t('document.title')}</Text>\n  <Icon name=\"arrow-new-tab\" size={16} />\n</Stack>;\n\n{\n  /* Vertical stack */\n}\n<Stack gap={16}>\n  <Text type=\"h2\">{i18n.t('section.heading')}</Text>\n  <Text type=\"body\">{i18n.t('section.description')}</Text>\n</Stack>;\n
\n
# Phlex — horizontal row\nstack(line: true, justify: \"space-between\", align: \"center\") do\n  text(type: \"caption-bold\") { t(\"document.title\") }\n  icon(name: \"arrow-new-tab\", size: 16)\nend\n\n# Phlex — vertical stack\nstack(gap: 16) do\n  text(type: \"h2\") { t(\"section.heading\") }\n  text(type: \"body\") { t(\"section.description\") }\nend\n
\n

Stack is best suited for page-level layout and smart components where you want to control spacing without adding a new stylesheet. For complex dumb components, defining flex layout directly in the component's SCSS is often the better choice — it avoids an extra wrapper element, keeps the markup flatter, and makes viewport-specific adjustments easier to reason about in one place.

\n

Box

\n

Use Box when you need to apply padding around content or constrain the width of a section. Pass a padding object with vertical, horizontal, top, bottom, left, or right values in pixels.

\n
<Box padding={{ vertical: 16, horizontal: 24 }}>\n  <Stack gap={8} line align=\"center\">\n    <Icon name=\"document\" size={24} />\n    <Text type=\"caption-bold\">{i18n.t('document.name')}</Text>\n  </Stack>\n</Box>\n
\n
# Phlex\nbox(padding: { vertical: 16, horizontal: 24 }) do\n  stack(gap: 8, line: true, align: \"center\") do\n    icon(name: \"document\", size: 24)\n    text(type: \"caption-bold\") { t(\"document.name\") }\n  end\nend\n
\n

Avoid using Box solely for visual decoration. If you need a background color or border, that belongs in the component's own BEM styles, not in Box props.

\n

Collapse

\n

Use Collapse to show or hide content in response to user interaction. Use it for accordions, expandable sections, and any other toggle-reveal pattern.

\n
const [open, setOpen] = useState(false);\n\n<Collapse open={open}>\n  <Button onClick={() => setOpen(!open)} />\n  <Text type=\"body\">{i18n.t('section.details')}</Text>\n</Collapse>;\n
\n
# Phlex\ncollapse(open: false) do\n  text(type: \"body\") { t(\"section.details\") }\nend\n
\n

Text

\n

Use Text for all rendered copy that requires a specific typographic style. Pass the desired variant via the type prop — the available types are generated directly from the Figma design variables (see the Figma section), so they always match what is in the design file. Never use bare HTML heading or paragraph tags when a specific style is intended.

\n

The type and color values are defined in the project's types.ts, which is generated from Figma variables. Always use these TypeScript types rather than raw strings to keep values in sync with the design system.

\n

Text accepts an element prop to control which HTML node is rendered, keeping semantic markup correct independently of the visual style. When no element is given, Text renders as a div — it never infers the element from the type, so visual style and semantic element are always chosen explicitly. The type already handles responsive sizing across all viewports. Additional helper props like uppercase, inline, and noWrap cover common typographic adjustments, and text color is also managed through Text rather than custom CSS.

\n
{/* Correct */}\n<Text type=\"h1\">{i18n.t('page.title')}</Text>\n<Text type=\"caption-bold\">{i18n.t('document.label')}</Text>\n\n{/* Wrong — do not use bare HTML tags for styled text */}\n<h1>Page title</h1>\n<strong>Document label</strong>\n\n{/* Control semantic element independently of visual style */}\n<Text type=\"h1\" element=\"h2\">{i18n.t('section.heading')}</Text>\n
\n
# Phlex — correct\ntext(type: \"h1\") { t(\"page.title\") }\ntext(type: \"caption-bold\") { t(\"document.label\") }\n\n# Phlex — wrong: do not use bare HTML tags for styled text\nh1 { \"Page title\" }\nstrong { \"Document label\" }\n\n# Control semantic element independently of visual style\ntext(type: \"h1\", element: :h2) { t(\"section.heading\") }\n
\n

States

\n

Every component that can wait, fail, or return nothing must account for all three conditions explicitly. Do not leave loading, error, or empty states as afterthoughts — design and implement them alongside the happy path.

\n\n

Always follow the Design team's specifications for these states and discuss implementation details with them before building. Loading skeletons, error messages, and empty states all have visual implications — do not implement them unilaterally.

\n

If the component receives data through props, the parent is responsible for passing the correct state down. The component itself should not decide how to fetch or retry — it should only render what it receives.

\n

Images

\n

All images must be in webp or svg format. Do not use png or jpeg. Use svg for icons and illustrations that need to scale without quality loss. Use webp for photographs and raster assets. Always provide meaningful alt text for accessibility.

\n

Styling

\n

CSS

\n

File Structure

\n

Stylesheets are co-located with the component they style. Each component owns exactly one stylesheet file, which defines exactly one BEM block. Styles are written mobile-first: base rules target small screens and larger-screen adjustments are layered with media queries at the standard breakpoints — 768px for tablet and 1280px for desktop.

\n

Colors

\n

Always use CSS custom properties for colors. Color values are defined as design tokens in Figma and exported to generated-variables.scss (see the Figma section). This keeps color themes centralized and supports future additions like dark mode.

\n

Never use hex color values in stylesheets. This includes bare hex values and hex fallbacks inside var() calls. If a variable is missing, the broken color should be visible so it gets fixed — not silently hidden by a fallback. If a variable does not exist in generated-variables.scss, ask the designer to add it in Figma and re-export.

\n
// Wrong — bare hex value\nbackground: #fff;\n\n// Wrong — hex fallback inside var(); broken colors must be visible, not hidden\nbackground: var(--neutral-surface-default, #fff);\n\n// Correct — variable only\nbackground: var(--neutral-surface-default);\n
\n

Inline Styles

\n

Do not use inline styles in markup — all styling must go through the component's stylesheet.

\n

The only accepted exception is declaring CSS custom properties inside the base layout primitives (Stack, Box, Grid). This exception does not extend to page or feature components.

\n
{\n  /* Wrong — never use inline styles */\n}\n<div style={{ color: 'red', marginTop: 16 }}>...</div>;\n\n{\n  /* Correct — express all styling through BEM classes and the stylesheet */\n}\n<div className=\"document-card__title document-card__title--error\">...</div>;\n
\n
# Phlex — wrong: never use inline styles\ndiv(style: { color: \"red\", margin_top: 16 }) { \"...\" }\n\n# Phlex — correct: express all styling through BEM classes and the stylesheet\ndiv(class: \"document-card__title document-card__title--error\") { \"...\" }\n
\n

Specificity

\n

Do not use !important. The only accepted exception is overriding styles from a closed third-party library where no selector-specificity solution is possible.

\n

Never target another component's classes from inside a different component's stylesheet. Rules like .stack .text {} are forbidden — each component is responsible for its own styles only and must never reach into or depend on another component's context.

\n

Avoid overly complex selectors. In particular, avoid :has() selectors with deep or broad matches — they are evaluated continuously by the browser and can cause severe layout performance issues in Safari. If you need :has(), keep it shallow and scoped tightly to the component root.

\n

BEM

\n

Every styled element must carry a BEM class (naming convention reference). Do not target bare HTML tags like p, li, or h2 in stylesheets.

\n

BEM classes follow the pattern block__element--modifier:

\n\n
// Correct\n.card { ... }\n.card__title { ... }\n.card__title--featured { ... }\n\n// Wrong — deep nesting\n.card__body__title { ... }\n\n// Wrong — bare HTML element selector\n.card p { ... }\n
\n

A few rules to keep in mind:

\n\n

Mobile

\n

Mobile styles follow from the mobile-first base rules, but a few patterns apply specifically to small-screen layouts:

\n\n

Accessibility

\n

Accessibility is a first-class requirement, not a post-launch checklist item. Build it in from the start.

\n\n

Figma

\n

Figma is the source of truth for all visual design. Text sizes and colors are defined there as variables. To generate the corresponding CSS custom property rules, use the figma-export-variables-plugin:

\n
    \n
  1. Clone the plugin repository and build it locally.
    2. \n
  2. Open Figma in the native macOS app (the web app does not support local plugins).
    3. \n
  3. Go to Plugins → Development → Import plugin from manifest.
    4. \n
  4. Select the built manifest.json file.
    5. \n
  5. Run the plugin from the Plugins menu whenever design tokens change to keep CSS variables in sync. Never hardcode color or typography values that should come from the design tokens.
    6. \n
\n

Components in Figma are designed at three breakpoints: mobile, tablet, and desktop. Always implement from the smallest breakpoint upward, adding adjustments for larger screens as you go. This keeps styles mobile-first by default and avoids having to override rules downward.

\n

Localization

\n

All user-facing text must come from locale files — never hardcode strings directly into markup. This applies to labels, button text, headings, error messages, and any other copy visible to the user.

\n

The Figma file for the screen is the source of truth for all copy. Always take text content from the Figma design for that screen, not from assumptions or placeholder text.

\n
{\n  /* Correct */\n}\n<Text type=\"body\">{i18n.t('dashboard.welcome_message')}</Text>;\n\n{\n  /* Wrong — hardcoded string */\n}\n<Text type=\"body\">Welcome back!</Text>;\n
\n
# Phlex — correct\ntext(type: \"body\") { t(\"dashboard.welcome_message\") }\n\n# Phlex — wrong: hardcoded string\ntext(type: \"body\") { \"Welcome back!\" }\n
\n

Locale keys are organized by feature using namespaces, for example navigation.dashboard or dashboard.current_month_overview. Leaf keys use lower_snake_case and should be named after the meaning of the text, not its literal content.

\n

Each page must implement its own copy — do not use generic or shared translations. Sharing a key across multiple screens makes it impossible to update copy for one page without affecting others.

\n

Keys must be derived from the copy they represent, not numbered sequentially:

\n
# Wrong\nparagraph_1: 'Are you sure you want to delete this item?'\nparagraph_2: 'This action cannot be undone.'\nparagraph_3: 'Confirm deletion'\n\n# Correct\nare_you_sure_you_want_to_delete_this_item: 'Are you sure you want to delete this item?'\nthis_action_cannot_be_undone: 'This action cannot be undone.'\nconfirm_deletion: 'Confirm deletion'\n
\n

When adding a new piece of UI text, add the key to the locale source file before using it in the component. Consult the project's own documentation for the canonical location of that file.

\n

Formatting

\n

Use a Formatter class for currency, percentages, dates, and datetimes. Never format these values inline or with hand-rolled string manipulation. The class is carried over from project to project — check an existing project for the canonical source before implementing from scratch.

\n

In React, instantiate it with the active locale (typed to the project's Locale type from i18n.ts) so all output stays consistent with the user's language settings. The class wraps the Intl APIs and handles null/invalid inputs gracefully.

\n
export class Formatter {\n  currency(value: number | string): string {}\n  percentage(value: number): string {}\n  date(value: Date | string): string | null {}\n  datetime(value: Date | string): string | null {}\n}\n
\n

In Rails, use the built-in i18n helpers:

\n
number_to_currency(invoice.total, unit: '€')\nnumber_to_percentage(value, precision: 1)\nl(invoice.due_date, format: :long)\nl(invoice.created_at, format: :long)\n
\n

Component Structure

\n

Each component in React is a single exported function declared with function, not an arrow function. The file exports exactly one component, named identically to the file. The return type must be declared explicitly as ReactElement. Do not use React.FC.

\n

Phlex follows the same one-component-per-file rule. Props are declared with the literal gem rather than a TypeScript interface.

\n
interface Props {\n  title: string;\n  url: string;\n}\n\nexport function DocumentCard({ title, url }: Props): ReactElement {\n  return (\n    <Box padding={{ vertical: 16, horizontal: 24 }}>\n      <Text type=\"caption-bold\">{title}</Text>\n    </Box>\n  );\n}\n
\n

Props and Typing

\n

Props must always be declared with an explicit interface. Declare only the specific fields the component needs — prefer Pick over accepting a full model type.

\n
// Wrong — accepts the entire User object when only two fields are needed\ninterface Props {\n  user: User;\n}\n\n// Correct — declare only what is actually used\ninterface Props {\n  user: Pick<User, 'name' | 'email'>;\n}\n
\n

In Phlex, use prop :field, Type from the literal gem and declare only the fields the component needs — the same principle applies.

\n
prop :name, String\nprop :email, String\n
\n

useEffect

\n

Avoid useEffect unless there is no other option. Common component-level misuses to avoid:

\n\n

Before reaching for useEffect, ask whether the same outcome can be achieved without it.

","frontmatter":{"title":"Components","shortTitle":"Components","breadcrumbs":[{"title":"Handbook","path":"/handbook"},{"title":"n.U.T.S","path":"/handbook/nuts"}]},"headings":[{"value":"Presentational (Dumb) Components","depth":2},{"value":"File Structure","depth":3},{"value":"Primitives","depth":3},{"value":"Grid","depth":4},{"value":"Icon","depth":4},{"value":"Stack","depth":4},{"value":"Box","depth":4},{"value":"Collapse","depth":4},{"value":"Text","depth":4},{"value":"States","depth":3},{"value":"Images","depth":2},{"value":"Styling","depth":2},{"value":"CSS","depth":3},{"value":"File Structure","depth":4},{"value":"Colors","depth":4},{"value":"Inline Styles","depth":4},{"value":"Specificity","depth":4},{"value":"BEM","depth":3},{"value":"Mobile","depth":3},{"value":"Accessibility","depth":2},{"value":"Figma","depth":2},{"value":"Localization","depth":2},{"value":"Formatting","depth":2},{"value":"Component Structure","depth":2},{"value":"Props and Typing","depth":3},{"value":"useEffect","depth":3}]}},"pageContext":{}}, "staticQueryHashes": ["63159454"]}