`, etc.), `data-size` controls **UI density** (padding, control heights) for descendants. Values: `sm` (compact), `md` (default), `lg` (spacious). > ⚠ **Name collision.** On `Heading`, `Button`, `Info`, and several other components, `data-size` is a **component-local visual size** (e.g. `2xs`–`2xl` on `Heading`), not density. Always check the component's doc. Do not use `data-size` to change font-size on plain HTML elements — wrap in ``, ``, or `` instead. ### 4.3 `data-tooltip` — tooltip text Place on any element. Tooltip text is automatically exposed to assistive tech. Use `data-tooltip-position="top│right│bottom│left"` to reposition. ```tsx ``` --- ## 5. Token system Tokens are namespaced `--mtds-*` (system) and `--mtdsc-*` (per-component override). All pixel values are **informative only** — the scale is fluid (resizes with density and root font-size). Always reference the token, never the literal value. ### 5.1 Spacing — `--mtds-{n}` Prefer layout primitives (`Flex`, `Grid`, `Card`, `Group`) with `data-gap`, `data-pad`, or `data-items` over raw spacing tokens. Do **not** set `margin` — use `data-gap` or `data-pad`. Valid `n` values: **`0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 22, 26, 30`** (note the gap above 15). At default density, `n × 4 ≈ pixels`. Other indexes (`16`, `17`, `19`, `20`–`21`, `23`–`25`, `27`–`29`) **do not exist**. ```css /* Do */ .x { padding: var(--mtds-4); gap: var(--mtds-3); } /* Don't */ .x { padding: 16px; } /* raw px */ .x { padding: var(--mtds-16); } /* not in the scale */ ``` ### 5.2 Color — `--mtds-color-{role}-{variant}` Use **palette-agnostic** tokens. They resolve against the nearest ancestor's `data-color`. | Role | Variants | |---|---| | `background` | `default`, `tinted` | | `surface` | `default`, `tinted`, `hover`, `active` | | `border` | `subtle`, `default`, `strong` | | `text` | `subtle`, `default` | | `base` | `default`, `hover`, `active`, `contrast-subtle`, `contrast-default` | Roles are **not interchangeable**: text tokens are for text, surface tokens are for surfaces, etc. ```css /* Do — works under any data-color */ .my-very-custom-component { background: var(--mtds-color-surface-default); color: var(--mtds-color-text-default); border: 1px solid var(--mtds-color-border-default); } ``` Palette-prefixed tokens like `--mtds-color-danger-surface-tinted` exist in the CSS but **must not** be used directly. To get a danger surface, set `data-color="danger"` on a parent and use the agnostic token. ### 5.3 Typography Prefer the components (`Heading`, `Ingress`, `Muted`, `Info`) over raw font-size tokens in markup. For custom CSS only: ```css --mtds-font-family /* "Mattilsynet Sans" */ --mtds-font-weight-regular /* 400 */ --mtds-font-weight-medium /* 500 */ --mtds-font-weight-semibold /* 600 */ --mtds-font-weight-bold /* 700 */ --mtds-font-size-muted /* used by */ --mtds-line-height-sm | -md ``` Heading sizes (`2xs`–`2xl`) and body sizes (`xs`–`xl`) are exposed via the typography components — use ``, not the underlying token. ### 5.4 Other tokens ```css --mtds-border-radius-sm | -md | -lg | -xl | -full --mtds-border-width-default | -focus --mtds-box-shadow-sm | -md | -lg --mtds-icon-size /* = --mtds-6 */ --mtds-icon-size-sm /* = --mtds-5 */ ``` ### 5.5 Per-component overrides — `--mtdsc-{component}-{property-path}` Each component exposes scoped custom properties. Discover the available ones for any component at the bottom of `mtds/ai/.mdx` (the `` block). ```css .scoped { --mtdsc-button-border-color: var(--mtds-color-border-strong); } .wide { --mtdsc-prose-max-width: 60rem; } ``` --- ## 6. App layout (page shell) Every Mattilsynet web application/page MUST be built inside the `App` shell. It is the outermost layout that all other content lives within. | Sub-component | Purpose | |---|---| | `App` | The shell. Supports `data-variant="mobilebar"` (see §6.6) | | `App.Header` | Logo + global actions. `` MUST be the first child | | `App.Toggle` | Expand/minimize sidebar (also opens it as a modal on mobile) | | `App.Sidebar` | Primary navigation. Modal on mobile, rail/expanded on desktop | | `App.Sticky` | Scroll-direction-aware sticky wrapper for sidebar contents only | | `App.Main` | Page content. Every leaf node MUST sit inside a `` or `` (see §6.3) | | `App.Footer` | Optional footer | | `App.Script` | SSR/Next.js only. Render in `` to prevent FOUC (see §6.7) | Required source order: **`App.Header` → `App.Toggle` → `App.Sidebar` → `App.Main` → `App.Footer`**. ### 6.1 Canonical composition ```tsx import { App, Logo, Button, Popover, Avatar, Card } from '@mattilsynet/design/react'; import { BellIcon, UserIcon, SignOutIcon, GearIcon, SignatureIcon, ListChecksIcon, MagnifyingGlassIcon, PlantIcon } from '@phosphor-icons/react/ssr'; Digiplant

{/* page content here — see §6.3 */} ``` ### 6.2 Sidebar buttons MUST be icon-only Every interactive child of `` MUST contain **only an icon** as visible content. The textual label MUST be supplied via `data-tooltip="…"` (and `aria-label` where the icon alone is not self-descriptive). The design system manages how labels appear: when the sidebar is minimized the tooltip is shown on hover; when expanded the design system reveals the label inline automatically. Hard-coding text inside the button breaks both states. ` // Don't — visible text inside a sidebar button ``` ### 6.3 `App.Main` content rules (the centering rule) `` is a layout region, not a content surface. - Every **leaf** node (text, heading, paragraph, raw HTML element) inside `` MUST be wrapped in at least one `` or ``. - Layout primitives (``, ``) MAY sit between `` and the ``/`` — but if you need to apply `data-center`, you must have a `` or `` as parent. - Use `` for a single related content unit on a solid surface (e.g. one inspection, one entity detail page). - Use `` for a collection of cards or meta-UI on a tinted surface. ```tsx // Do Tilsyn 12345

…

… … // Do multiple Cards in Group in App.Main Liste over tilsyn … … // Don't — bare content directly in App.Main Tilsyn 12345

…

// Don't — data-center on App or App.Main … // Don't — data-center on direct child of App.Main ``` ### 6.4 Expand / minimize sidebar - `` renders the standard expand/minimize button. - Do **not** manage sidebar visibility with custom React state — always use ``. ### 6.5 Sticky sidebar content Wrap the contents of `` in `` to get scroll-direction-aware sticky behavior (the sidebar stays visible when scrolling up and slides away when scrolling down). `` is for sidebar contents — do not use it elsewhere. ### 6.6 Mobile bottom bar variant ```tsx … ``` - Converts the sidebar into a mobile bottom navigation bar. - Use only when there are 5 or fewer top-level navigation items. - Headings, dividers, and elements with `data-app-expanded="false"` are auto-hidden in this variant. ### 6.7 SSR / Next.js To prevent flash of unstyled content (FOUC) when the persisted expanded/minimized state is restored, render `` inside ``: ```tsx // app/layout.tsx (Next.js) {children} ``` --- ## 7. Layout primitives ### 7.1 When to use which | Component | Use when | Surface | |---|---|---| | `Flex` | Children have different widths (button rows, toolbars) | none | | `Grid` | Children should be equal-width (card grids) or stack vertically | none | | `Card` | Group related content as a single unit | `surface-default` (white) | | `Group` | Group several cards or meta-UI as a region | `background-tinted` (translucent grey) | `Card` MAY be nested inside `Group`. Avoid `Card` inside `Card`. ### 7.2 Shared attributes — `Flex` and `Grid` | Attribute | Values | Notes | |---|---|---| | `data-gap`, `data-row-gap`, `data-column-gap` | Same set as §5.1 (`0`–`15`, `18`, `22`, `26`, `30`) | Default `data-gap="3"` | | `data-items` | `auto`, `full`, or `25`, `50`, `75`, `100`, `150`, `200`, `250`, `300`, `350`, `400`, `450`, `500` | Min child width in **px** before wrapping. `full` = single column (Flex only). `auto` = intrinsic | | `data-align` | `normal`, `stretch`, `start`, `center`, `end` | `align-items` | | `data-align-content` | `start`, `center`, `end`, `space-between`, `space-around`, `space-evenly` | `align-content` | | `data-justify` | `start`, `center`, `end`, `space-between`, `space-around`, `space-evenly` | `justify-content` | | `data-center` | `sm`, `md`, `lg`, `xl`, `2xl` | Max-width + center + side padding. | | `data-nowrap` | boolean | Prevent wrapping | | `data-fixed` | boolean | Children don't grow (Flex) / `auto-fill` (Grid) | ### 7.3 Flex child attributes | Attribute | Values | Notes | |---|---|---| | `data-self` | Same set as `data-items` | Min width for this child | | `data-align-self` | `start`, `center`, `end`, `stretch` | | | `data-justify-self` | `start`, `center`, `end` | | ### 7.4 `Card` and `Group` | Attribute | Values | Notes | |---|---|---| | `data-pad` | Single index from §5.1, or `{vertical}-{horizontal}` (e.g. `4-6`) | Inner padding. Default `5`. Pair form is fluid between viewport breakpoints | | `data-radius` | `sm`, `md`, `lg`, `xl` | Defaults: Card `lg`, Group `xl` | `Card` only: | Attribute | Values | Notes | |---|---|---| | `href` | string | Renders Card as `` (whole card becomes a link) | | `data-clickdelegatefor` | CSS selector | Click anywhere on the card triggers the matching descendant (e.g. `"#details-link"`) | ### 7.5 Quick reference ```tsx // Page container, centered, max-width 2xl Page title // Button row // Responsive equal-width card grid Card 1 Card 2 Card 3 ``` --- ## 8. Typography components ### 8.1 `Heading` | Attribute | Values | Notes | |---|---|---| | `as` | `h1`–`h6` | **Semantic** level. Default `h2`. Always set explicitly for accessibility | | `data-size` | `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl` | **Visual** size (independent of `as`) | | `data-justify` | `start`, `center`, `end` | Text alignment | `Heading` auto-sizes and aligns any `

`, `

`–`

`, `
`, and ``. - Default max-width: `45rem` (override with `--mtdsc-prose-max-width`). - Layout primitives (``, ``) inside `` will also receive the rhythm margin — keep them outside `` if you don't want that. ```tsx Section
Body text with automatic rhythm.

Item
``` ### 8.3 `Ingress` and `Muted` ```tsx Lead paragraph introducing the topic. Last updated 06.05.2026 ``` ### 8.4 `Info` Responsive label + value layout. Use for metadata, key/value pairs, or a value next to an indicator icon. Wrap the label in ``. | Attribute | Values | Notes | |---|---|---| | `data-variant` | `regular` (default), `circle` | `circle` wraps the icon in a colored circle. Use only when the icon must draw visual attention; show both label and value | ```tsx // Label + value OrganizationFisk AS // Icon + label + value StatusApproved // Emphasised: icon in colored circle (palette comes from ancestor data-color) StatusApproved ``` To color the circle, set `data-color` on an ancestor (e.g. wrap the `Info` in a ``). --- ## 9. Forms Forms in mtds compose `` (single input row), `
` (grouped fields), `` (top-of-form error list), and `` (field-level error message). The exact React export names matter — see §12. ### 9.1 `Field` — two usage modes Mode A (composition): wrap children manually. Use ``, ``, and an `` (or other input). Use this when you need fine control. ```tsx Name Your full legal name. ``` Mode B (polymorphic shorthand): `` renders the complete row. ```tsx ``` Supported `as` values: `"input"`, `"textarea"`, `"select"`, `Field.Suggestion`. Compound members: `Field.Label`, `Field.Description`, `Field.Suggestion`, `Field.Datalist`, `Field.Option`. ### 9.2 `Fieldset` — group related fields Use plain `` and `` for grouped options. There is no `Fieldset.Legend` component — use the native HTML `` element when composing manually, or use `` only inside the React `
` component (it renders ``). ```tsx
Hva foretrekker du? Pick one option.
``` ### 9.3 `Errorsummary` — top-of-form errors Note the spelling: `Errorsummary` (single capital R). Children are a `` + an unordered list of in-page anchors that point to field IDs. ```tsx import { Errorsummary, Heading } from '@mattilsynet/design/react'; For å gå videre må du rette opp følgende feil:

Name is required

Email must be valid

``` Behavior rules: - Hide the Errorsummary with `hidden` until validation fails. - Anchor links in Errorsummary must match field `id` attributes. On click, scroll the target into view and focus it. ### 9.4 `Validation` — field-level error Use `` (or `
` in plain HTML) as a child of `` or `
`. In Mode B (`Field as="…"`), pass `validation="…"` instead. ### 9.5 `Togglegroup` — single-select toggle button row Note the spelling: `Togglegroup` (single capital G). Compound: `Togglegroup.Item`. ```tsx List Grid ``` ### 9.6 `Fileupload` (experimental) Note the spelling: `Fileupload`. API may change — read `fileupload.mdx` before use. ### 9.7 `HelpText` Inline contextual help button (renders as a button that toggles a popover). Prefer passing `helpText="…"` and `helpTextLabel="…"` to `` over composing `` manually. ### 9.8 Worked form example ```tsx import { useRef, useState } from 'react'; import { Button, Card, Errorsummary, Field, Fieldset, Flex, Heading } from '@mattilsynet/design/react'; function ApplicationForm() { const [errors, setErrors] = useState>({}); const summaryRef = useRef(null); const onSubmit = (e: React.FormEvent) => { e.preventDefault(); const data = new FormData(e.currentTarget); const next: Record = {}; if (!data.get('name')) next.name = 'Navn er påkrevd'; if (!data.get('email')) next.email = 'E-post er påkrevd'; setErrors(next); if (Object.keys(next).length) setTimeout(() => summaryRef.current?.focus()); }; return (

Foretrukket kontakt
); } ``` --- ## 10. Worked page example ```tsx import { Flex, Grid, Card, Heading, Prose, Muted, Button, Tag } from '@mattilsynet/design/react'; import { WarningIcon } from '@phosphor-icons/react/ssr'; export function InspectionsPage() { return ( Inspections {/* Compact toolbar — density cascades /} Fisk AS Approved Inspected 03.05.2026 {/ Single attribute switches whole card to red /} Kjøtt & Co
Critical violations. Follow up within 14 days.
); } ``` --- ## 11. Figma → code & pre-return checklist When the input is a Figma frame/sketch, treat the design as a binding spec for which design system components to use, not just a pixel target. ### 11.1 Figma component names map 1:1 to mtds component names A Figma instance named Card → ``. Field → ``. Errorsummary → ``. Info → ``. Look up the Figma component name in §12 and use the matching React component. There is no name remapping table — if the names differ, the Figma library is out of date; ask before guessing. ### 11.2 Mapping rules - Map every visible Figma component instance to its corresponding component from `@mattilsynet/design/react`. Do not substitute custom HTML/CSS to gain layout control. - Do not reach for raw `
`/`` + CSS when a design system component covers the case — even if the component feels harder to make responsive. First try the component plus a wrapper (`Flex`, `Grid`, `Card`) and/or token-based CSS. - Auto-layout: if children of a Figma auto-layout have equal width or width "fill", prefer `` over ``. - Metadata (icon + value, or label + value): MUST use `` whenever Figma uses an `Info` instance, or whenever the content shape is icon + value or label + value. Custom ``/`
` structures for metadata are not allowed unless the user explicitly approves the deviation. - Headings: any Figma text styled as a heading → ``, never raw `
`–`
` or styled `
`. - Lead/intro text → ``. Secondary/meta text → ``. - Surface containers: Figma "Card" → ``; Figma tinted region grouping cards → ``. - Buttons, Tags, Chips, Alerts, Tabs, Steps, Dialog, Popover, Table, Field/Fieldset, Errorsummary → use the matching component from §12. Do not reimplement. - Color regions: when a Figma frame is in a semantic color (danger/warning/success/info/inverted), set `data-color="…"` on a parent rather than picking palette-prefixed tokens. - If you genuinely believe a deviation is required (e.g. the component cannot express the intended behavior), STOP. Explain the deviation and the proposed alternative before writing code, and wait for explicit approval. - If the sketch is unclear (text unreadable, intent unknown, missing state), list assumptions explicitly at the top of your final answer. ### 11.3 Pre-return checklist Before sending the final response, verify every item: Imports & setup - [ ] React components imported from `@mattilsynet/design/react`; icons from `@phosphor-icons/react/ssr`. - [ ] Entry file imports `'@mattilsynet/design'` and `'@mattilsynet/design/styles.css'`. - [ ] Exact export names spelled correctly: `Errorsummary`, `Togglegroup`, `Fileupload`, `HelpText`. Spacing, color, sizing - [ ] No raw `px`/`rem` for spacing — only `data-gap`, `data-pad`, or `var(--mtds-{n})` from the §5.1 scale. - [ ] No hex/rgb/named colors — only `var(--mtds-color-)` (palette-agnostic) under the right `data-color` parent. - [ ] No inline `style={{…}}` for layout/color/spacing. - [ ] No Tailwind utility classes. - [ ] All spacing-token indexes used exist (`0`–`15`, `18`, `22`, `26`, `30`). - [ ] `data-size` collisions accounted for (density on containers vs. local size on `Heading`/`Button`/`Info`). Markup - [ ] No raw `
`–`
` — every heading is ``. - [ ] No raw `
` — use `` or ``. - [ ] Metadata pairs (icon + value / label + value) use ``, not custom ``/`
`. App shell - [ ] `` wraps the page; source order `Header → Toggle → Sidebar → Main → Footer`. - [ ] Every leaf node inside `` is wrapped in `` or ``. - [ ] `` is the first child of ``. - [ ] Sidebar buttons are icon-only with `data-tooltip="Label"`. - [ ] Sidebar state uses `` and `` Figma audit (when converting from a sketch) - [ ] Every visible Figma component instance is mapped to its `@mattilsynet/design/react` counterpart, or listed as an explicit, approved deviation. --- ## 12. Component index Each component has full docs at `./ai/.mdx` and examples in `./ai/.stories.tsx`. Read the relevant doc before using a component you have not used in this session. ### Layout & structure - `App` — page shell with `Header`, `Toggle`, `Sidebar`, `Sticky`, `Main`, `Footer`, `Script`. See §6. - `Card` — solid white surface for one related content unit. `data-pad`, `data-radius`, `href`, `data-clickdelegatefor`. See §7.4. - `Group` — tinted surface for a region of cards or meta-UI. Same attrs as `Card`. See §7.4. - `Flex` — flex container for mixed-width children (toolbars, button rows). See §7.2. - `Grid` — grid container for equal-width columns or vertical stacks. Use `data-items="300"` for responsive. See §7.2. - `Divider` — visual separator (`
` styling). ### Typography - `Heading` — `as="h1".."h6"` for semantics, `data-size="2xs".."2xl"` for visual size. See §8.1. - `Prose` — apply vertical typographic rhythm to direct children (body text, lists, headings). See §8.2. - `Ingress` — lead/intro paragraph. See §8.3. - `Muted` — small/secondary text. See §8.3. - `Info` — label + value pair, optionally with icon. `data-variant="regular│circle"`. See §8.4. - `Link` — inline anchor styled to mtds. ### Forms (see §9) - `Field` — single field row. Two modes: composition (``+``) or polymorphic (``). Compound: `Label`, `Description`, `Suggestion`, `Datalist`, `Option`. - `Fieldset` — group related fields. Compound: `Legend`, `Description`. - `Input` — form control primitive (``, used inside ``). - `Validation` — field-level validation message. Pass via `validation="…"` on ``, or render directly inside ``. - `Errorsummary` — top-of-form error list (note: single capital R). Children: `` + `
`. See §9.3. - `Togglegroup` — single-select toggle button row (single capital G). Compound: `Item`. See §9.5. - `Fileupload` — file upload (experimental). See §9.6. - `HelpText` — popover-style help button. Prefer ``. See §9.7. ### Actions - `Button` — primary action element. Renders `` when `href` is set. Variants: `data-variant="primary│secondary│tertiary"`. Sizes via `data-size` on the button or its container. - `Chip` — interactive filter chip / single-select toggle. ### Feedback & status - `Alert` — inline contextual feedback. Color via ancestor `data-color="info│success│warning│danger"`. - `Badge` — small status indicator overlay (count, dot) on top of another element. - `Progress` — progress bar. - `Skeleton` — loading placeholder block. - `Spinner` — loading spinner. - `Tag` — read-only label/keyword. Color via `data-color`. - `Toast` — transient notification (managed via toast helpers). ### Navigation - `Breadcrumbs` — breadcrumb trail. - `Pagination` — paged result navigation. - `Steps` — multi-step progress / timeline. Children are `
` with ``, ``, optional ``. Set `aria-current="step"` on the active `
`. State via `data-state="complete"` on the `
`/``. - `Tabs` — tabbed content panels. Compound: `List`, `Tab`, `Panel`. ### Display - `Avatar` — round user avatar. - `Chart` — chart wrapper. - `Details` — disclosure widget. Compound: `Summary`. - `Dialog` — modal dialog using native ``. Open with `command="show-modal"` + `commandfor="id"`; close with `command="request-close"`. - `Popover` — non-modal floating overlay using native popover API. Polymorphic via `as` (commonly `as="menu"`). Anchor with `popoverTarget="id"` on the trigger. - `Table` — data table. Compound: `Thead`, `Tbody`, `Tr`, `Th`, `Td`, `ThSortable`. - `Tooltip` — prefer `data-tooltip="…"` on any element instead of a component. ### Domain & branding - `Law` — Mattilsynet legal-text formatting. - `Logo` — Mattilsynet (or sub-app) logo. Required as the first child of ``. - `Print` — print-only utilities and breaks. ### Map and Charts - `Atlas` — interactive map. - `Chart` — chart primitives.

`–`

`–`

Title

`–`

`–`

`–`