# Duo Design System

> Accessible web components, design tokens, styles, and icons for Talentech products. Custom elements use the `duo-` prefix; tokens use `--duo-*` CSS variables.

Published packages: @duo/tokens@1.0.1, @duo/styles@3.0.0, @duo/icons@0.2.0, @duo/ui@1.5.0, @duo/assets@0.2.0, @duo/locales@1.2.0, @duo/email-templates@0.3.4

## Agent notes

- Consult Duo docs before writing UI; prefer `<duo-*>` components over bespoke markup.
- Load `@duo/tokens/css`, then `@duo/styles`, then `@duo/ui` (see component Setup sections).
- Raw markdown mirrors: `/raw/site/`, `/raw/packages/`, `/raw/ai/`.
- Foundation catalogues: `/raw/site/foundation/icons.md`, `/raw/site/foundation/assets.md`, `/raw/site/foundation/tokens.md`.
- Form markup: `/raw/site/guidelines/forms.md` and `/raw/site/components/field.md`.
- Template catalogues: `/raw/site/templates/` (HTML and email).
- Agent skills: `/.well-known/agent-skills/` — install with `npx skills add https://design.talentech.io`.
- Human guides: `/ai/skills/`, `/ai/llms-txt/`.

## Site

### Getting started

- [About](https://design.talentech.io/raw/site/getting-started/about.md): Introduction to Duo, the Talentech design ecosystem, and the Duo Design System.
- [CDN](https://design.talentech.io/raw/site/getting-started/cdn.md): Load Duo tokens, styles, and web components from versioned CDN URLs without npm.
- [Get started](https://design.talentech.io/raw/site/getting-started/get-started.md): Install Duo packages in your application, import tokens and styles, and run the design-system monorepo locally.
- [Getting started](https://design.talentech.io/raw/site/getting-started/index.md): Start here to learn what Duo is and how to use it in your product or in the design-system monorepo.

### Foundation

- [Assets](https://design.talentech.io/raw/site/foundation/assets.md): Illustrations, product logos, and country flags from @duo/assets.
- [Design tokens](https://design.talentech.io/raw/site/foundation/tokens.md): CSS custom properties from @duo/tokens for use in var(--duo-*).
- [Icons](https://design.talentech.io/raw/site/foundation/icons.md): A catalogue of every icon exported by @duo/icons for use with duo-icon.

### Components

- [Avatar](https://design.talentech.io/raw/site/components/avatar.md): Show a person or entity with a photo, icon, initials, or slotted content.
- [Badge](https://design.talentech.io/raw/site/components/badge.md): Compact status or count label from @duo/ui.
- [Banner](https://design.talentech.io/raw/site/components/banner.md): Inline alert-style messaging from @duo/ui.
- [Box](https://design.talentech.io/raw/site/components/box.md): Groups and separates content (notes in prose, cards in grids, dialog bodies).
- [Brand attribution](https://design.talentech.io/raw/site/components/brand-attribution.md): Platform attribution with the Talentech wordmark and a “Powered by” label.
- [Button](https://design.talentech.io/raw/site/components/button.md): Action control with native <button> or <a> semantics, variants, loading, and slots for icon/badge.
- [Card](https://design.talentech.io/raw/site/components/card.md): Grouped content surface with optional media, header, body, and footer actions.
- [Center](https://design.talentech.io/raw/site/components/center.md): Center content horizontally with optional gutters, max width, and text alignment.
- [Chip](https://design.talentech.io/raw/site/components/chip.md): Compact colored label with optional icon and dismiss control.
- [Confirm button](https://design.talentech.io/raw/site/components/confirm-button.md): Two-step inline confirmation that turns a default button into a danger button after the first click.
- [Cookie banner](https://design.talentech.io/raw/site/components/cookiebanner.md): First-party cookie consent modal for kuntarekry and kirkkorekry, with bundled fi, en, and sv content.
- [Cover](https://design.talentech.io/raw/site/components/cover.md): Column layout with optional top band, a growing centered main region, and optional bottom band.
- [Databox](https://design.talentech.io/raw/site/components/databox.md): Compact metric tile with a prominent value, supporting label, and optional trend.
- [Description list](https://design.talentech.io/raw/site/components/description-list.md): Semantic term/value rows for labelled metadata and amounts.
- [Divider](https://design.talentech.io/raw/site/components/divider.md): Separate content with a horizontal rule and optional centered label text.
- [Editor](https://design.talentech.io/raw/site/components/editor.md): Rich text editor with Duo-themed Froala toolbar presets.
- [Empty state](https://design.talentech.io/raw/site/components/empty-state.md): Communicate an empty dataset or unavailable feature with copy and optional actions.
- [Field](https://design.talentech.io/raw/site/components/field.md): Wrapper for native form controls in the light DOM.
- [File input](https://design.talentech.io/raw/site/components/file-input.md): Segmented native file picker with filename field, browse, and optional clear.
- [Icon](https://design.talentech.io/raw/site/components/icon.md): Inline SVG icon from @duo/icons.
- [List](https://design.talentech.io/raw/site/components/list.md): Stacked rows with optional title, wrapper, and split-header groups.
- [List group](https://design.talentech.io/raw/site/components/list-group.md): Group list rows with shared borders and separators.
- [Modal](https://design.talentech.io/raw/site/components/modal.md): Blocking dialog with header, body, and footer actions.
- [OTP input](https://design.talentech.io/raw/site/components/otp-input.md): Collect a fixed-length numeric one-time code in separate digit cells.
- [Poster](https://design.talentech.io/raw/site/components/poster.md): Full-height or inline promotional panel with copy and an illustration.
- [Price](https://design.talentech.io/raw/site/components/price.md): Right-aligned monetary amount with optional currency suffix from @duo/ui.
- [Radio card](https://design.talentech.io/raw/site/components/radio-card.md): Selectable card options in a vertical radio group with optional badges and trailing content.
- [Section](https://design.talentech.io/raw/site/components/section.md): Grouped content with optional title, subtitle, header actions, and a surface variant.
- [Sidebar](https://design.talentech.io/raw/site/components/sidebar.md): Responsive sidebar layout.
- [Stack](https://design.talentech.io/raw/site/components/stack.md): Generic flex stack utility component for vertical/horizontal layouts..
- [Stepper](https://design.talentech.io/raw/site/components/stepper.md): Horizontal step progress with numbered, current, and complete states.
- [Table](https://design.talentech.io/raw/site/components/table.md): Style wrapper for native HTML tables in the light DOM.
- [Tag](https://design.talentech.io/raw/site/components/tag.md): Short label or category marker..
- [Visually hidden](https://design.talentech.io/raw/site/components/visually-hidden.md): Hide copy from the visual layout while keeping it available to assistive technology.

### Guidelines

- [Accessibility guidelines](https://design.talentech.io/raw/site/guidelines/accessibility.md): WCAG 2.2 AA standards for semantic HTML, keyboard access, ARIA, forms, and contrast — with or without Duo.
- [Error message guidelines](https://design.talentech.io/raw/site/guidelines/error-messages.md): Clear, empathetic, actionable error copy that helps users recover quickly.
- [Form guidelines](https://design.talentech.io/raw/site/guidelines/forms.md): Native form controls in the light DOM with duo-field — markup order, helpers, errors, and accessibility.
- [Punctuation](https://design.talentech.io/raw/site/guidelines/punctuation.md): Grammar-based punctuation rules for product copy, including symbols and spacing.
- [Writing guidelines](https://design.talentech.io/raw/site/guidelines/writing.md): Voice, tone, clarity, and accessibility-oriented UX writing standards.

### Patterns

- [Inline Contextual Action Column](https://design.talentech.io/raw/site/patterns/action-column.md): The Inline Contextual Action Column is a table pattern that introduces a row-level action as a contextual, stage-dependent enhancement to bulk actions, positioned in an early column near primary data.
- [Inline Two-Step Confirmation](https://design.talentech.io/raw/site/patterns/inline-confirmation.md): An interaction pattern where a destructive action requires **two consecutive user actions** to complete, without using a modal or external confirmation UI.

### Templates

- [Email templates](https://design.talentech.io/raw/site/templates/email-templates.md): Browse and preview Duo transactional email templates.
- [HTML templates](https://design.talentech.io/raw/site/templates/html-templates.md): Static HTML examples demonstrating Duo components in full-page layouts.
- [Templates](https://design.talentech.io/raw/site/templates/index.md): Templates document layout and interface patterns in Duo and serve as worked examples.

### AI integration

- [Agent Skills](https://design.talentech.io/raw/site/ai/skills.md): Install Duo Design System skills for AI coding agents — components, tokens, styles, icons, and conformance rules.
- [AI integration](https://design.talentech.io/raw/site/ai/index.md): How AI coding agents discover and use Duo documentation, packages, and skills.
- [LLMs.txt](https://design.talentech.io/raw/site/ai/llms-txt.md): Point AI tools at Duo documentation via llms.txt and raw markdown mirrors.

### What's new

- [What’s new](https://design.talentech.io/raw/site/whats-new/index.md): Release notes and updates for the Duo design system.

## Packages

- [@duo/assets](https://design.talentech.io/raw/packages/assets/README.md): Versioned SVG illustrations, product logos, and country flags for the Duo design system. Sources live under `src/`; `pnpm build` copies them to `dist/` and generates `manifest.json`.
- [`@duo/cookiebanner`](https://design.talentech.io/raw/packages/cookiebanner/README.md): Cookie consent banner for Duo products. Uses the Duo modal template with bundled content for **kuntarekry** and **kirkkorekry** (fi / en / sv).
- [@duo/editor](https://design.talentech.io/raw/packages/editor/README.md): Froala-based `<duo-editor>` for the Duo Design System. Toolbar icons use `<duo-icon>` from `@duo/ui`.
- [Agent instructions: `@duo/email-templates`](https://design.talentech.io/raw/packages/email-templates/AGENTS.md): This package holds **React Email** templates and a **render + build** pipeline that outputs HTML and plaintext with **literal** `{{merge}}` tokens for downstream systems. **Translated copy** lives in 
- [@duo/email-templates](https://design.talentech.io/raw/packages/email-templates/README.md): **Localized email templates** (React Email) for downstream systems. This package **does not merge** recipient data in Node: it renders a **template bundle** (`dist/templates/`) where `{{placeholders}}
- [AI and human authoring guide: new email templates](https://design.talentech.io/raw/packages/email-templates/docs/AI-AUTHORING.md): Use this checklist when adding or changing templates so discovery, locales, build, and tests stay consistent.
- [Email template artifacts](https://design.talentech.io/raw/packages/email-templates/docs/ARTIFACTS.md): `@duo/email-templates` produces one **canonical bundle** from `pnpm build`. Ecosystem-specific packages only wrap that output.
- [Email template localization](https://design.talentech.io/raw/packages/email-templates/docs/LOCALIZATION.md): Translated email copy lives in **`@duo/locales`** (`packages/locales/src/email-templates/`). This package imports it via `@duo/locales/email-templates` — there is **no** Crowdin config here.
- [Product requirements: `@duo/template-email`](https://design.talentech.io/raw/packages/email-templates/docs/PRD.md): This package produces **localized transactional email artifacts** (HTML and plain text) for downstream sending systems. It uses **React Email** to render markup; **translated copy and subjects** come 
- [Support matrix: `@duo/template-email`](https://design.talentech.io/raw/packages/email-templates/docs/SUPPORT.md): This document states what the package **supports today** and what is **explicitly out of scope**, aligned with the implemented templates and the render/build pipeline.
- [@duo/fonts](https://design.talentech.io/raw/packages/fonts/README.md): Web font files and `@font-face` definitions for the Duo design system (Inter and Geist Mono). Sources live under `src/`; `pnpm build` copies them to `dist/`.
- [@duo/icons](https://design.talentech.io/raw/packages/icons/README.md): Curated SVG set built into one module with **`icons`** (kebab-case keys → SVG strings), **`IconName`**, **`iconMetadata`**, and **`iconCategories`**.
- [@duo/locales](https://design.talentech.io/raw/packages/locales/README.md): Translation strings for the design system, synced with [Talentech Crowdin Enterprise](https://talentech.crowdin.com/) (**Duo project 115**) via [`crowdin.yml`](./crowdin.yml).
- [@duo/styles](https://design.talentech.io/raw/packages/styles/README.md): Global **base** styles and **prefixed utilities** (`duo-u-*`) for native elements. This package uses design tokens from `@duo/tokens` but does **not** import them — you must load tokens first so `var(
- [@duo/tokens](https://design.talentech.io/raw/packages/tokens/README.md): Canonical design tokens for the Duo Design System.
- [Token Source Directory](https://design.talentech.io/raw/packages/tokens/src/README.md): **Base tokens** are authored under `src/base/` (`base.json` and `color-primitives.json`).
- [Email Tokens](https://design.talentech.io/raw/packages/tokens/src/email/README.md): Email-specific tokens live in `tokens.json` under a **`duo-email`** root. They follow the same W3C/DTCG leaf shape as base tokens (`$value`, `$type`, optional `$description`).
- [@duo/ui](https://design.talentech.io/raw/packages/ui/README.md): Web components (Lit) for the DUO design system.
- [Avatar Migration (React → `duo-avatar`)](https://design.talentech.io/raw/packages/ui/src/components/avatar/MIGRATION.md): This guide explains how to migrate from the legacy Storybook React `Avatar` (props: `avatarUrl`, `icon`, `altText`, `size`, `square`, `outline`) to the design-system **`duo-avatar`** web component.
- [Box Migration (React -> `duo-box`)](https://design.talentech.io/raw/packages/ui/src/components/box/MIGRATION.md): This guide explains how to migrate from the old React `Box` API to the new `duo-box` component API.
- [Button Migration (React `Button.tsx` -> `duo-button`)](https://design.talentech.io/raw/packages/ui/src/components/button/MIGRATION.md): <duo-icon slot="icon" name="check" size="s"></duo-icon>
- [Modal migration (legacy React → `duo-modal`)](https://design.talentech.io/raw/packages/ui/src/components/modal/MIGRATION.md): <Typography variant="p">{body}</Typography>

## AI

- [AI documentation](https://design.talentech.io/raw/ai/README.md): Agent-facing content for the Duo Design System. **Edit source files only in their home folders** — artifacts under `apps/docs/public/` are generated at build time.
- [AI Rules](https://design.talentech.io/raw/ai/rules/README.md): This directory is reserved for rules that guide AI-assisted work in the design-system repository.
- [Accessibility rules (design-system components)](https://design.talentech.io/raw/ai/rules/accessibility.md): Contract for **shared `<duo-*>` components** in the Duo monorepo. For product UI accessibility (with or without Duo), see [Accessibility guidelines](https://design.talentech.io/guidelines/accessibilit
- [Component Definition Rules](https://design.talentech.io/raw/ai/rules/component-definition.md): These rules define the minimum standard for new design-system components.
- [Language Rules](https://design.talentech.io/raw/ai/rules/language.md): Use English for all code-facing text in this repository.
- [Token Usage Rules](https://design.talentech.io/raw/ai/rules/token-usage.md): These rules define how design tokens must be used in the Duo Design System.
- [AI Skills](https://design.talentech.io/raw/ai/skills/README.md): Repeatable agent workflows for the Duo Design System and accessible frontend development.
- [Accessible Frontend Development](https://design.talentech.io/raw/ai/skills/accessible-frontend/SKILL.md): Write accessible frontend code following WCAG 2.2 AA standards, using semantic HTML and applying UI/UX best practices. Use this skill whenever generating or modifying HTML, React, Vue, or any frontend components — even if the user doesn't explicitly mention accessibility. Trigger on any request to build forms, buttons, modals, navigation, inputs, interactive elements, or UI layouts. Also trigger when reviewing existing code for a11y issues, or when the user mentions screen readers, keyboard navigation, ARIA, or contrast.
- [Audit Duo conformance](https://design.talentech.io/raw/ai/skills/audit-duo-conformance/SKILL.md): Review UI code for Duo Design System conformance — tokens, components, icons, accessibility, and package usage.
- [Build with Duo](https://design.talentech.io/raw/ai/skills/build-with-duo/SKILL.md): Build product UI with the Duo Design System. Use before writing or changing UI — consult Duo components, tokens, styles, and icons instead of bespoke markup.
- [Create Component](https://design.talentech.io/raw/ai/skills/create-component/SKILL.md): Create a new design-system web component in the Duo Design System repository. Use when the task is to scaffold a shared component with implementation, token-based styles, metadata, tests, Storybook stories, Astro docs page, and exports following repository conventions.
- [Document Component](https://design.talentech.io/raw/ai/skills/document-component/SKILL.md): Document a Duo design-system component for humans and AI — purpose, usage, accessibility, examples, and Astro docs page.