Use UI Kit

UI conventions for pearpass-app-browser-extension

This is the browser extension (Chrome MV3) for PearPass. It's written in React + TypeScript. The extension has four build targets — the action popup (src/action/), content scripts (src/content/) and their in-page popups (src/contentPopups/), an injected page script (src/inject/), and the background service worker (src/background/). UI is built on the shared component library @tetherto/pearpass-lib-ui-kit.

This document is for anyone contributing UI to the repo — new hires, current engineers, and AI coding assistants (Claude Code, Cursor, Codex, etc.). It captures the component catalog, styling conventions, file-naming rules, and patterns we use when building UI in this extension. Read it once before your first UI change; keep it open when you're in doubt.

Migration state — kit is the only design system

UI is fully on @tetherto/pearpass-lib-ui-kit. All screens and components use kit primitives. There is no EXTENSION_DESIGN_VERSION / isV2() runtime flag — those have been removed. Kit components render directly throughout.

A small number of legacy components remain in src/shared/components/ (e.g. Switch, SwitchWithLabel, TimerBar, ModalHeader) — carry-overs from the migration period. Do not grow that tree; use kit equivalents for any new work.

Never use the V2 suffix. It was a coexistence marker during the v1/v2 migration, which is now complete. All new files use their natural name.

Where UI lives in this repo

• src/action/pages/ — top-level screens for the action popup (WelcomePage, Settings, RecordDetails, RecordList, CreatePasskey, SelectPasskey, AuthenticatorView, AddDevice, NonSecureWarning).
• src/action/containers/ — stateful composed UI used by those pages.
• src/contentPopups/views/ — in-page popups rendered by the content script (Autofill, LoginDetect, PasswordGenerator, PasswordSuggestion, Logo).
• src/shared/components/ — legacy components (do not grow; use kit equivalents for new work).
• src/shared/containers/ — shared stateful UI (Sidebar, PassPhrase, CreateVaultModalContent, etc.).

Golden rules

1. Check the catalog below before creating any component. If it exists in the kit, use it — never wrap or reimplement.
2. All new UI goes through the kit. Any new .tsx/.jsx file — suffixed or not — must import from @tetherto/pearpass-lib-ui-kit, not from src/shared/components/.
3. Never add variants under src/shared/components/ (ButtonPrimary, ButtonSecondary, ButtonRoundIcon, ButtonFilter, ButtonFolder, ButtonCreate, ButtonLittle, ButtonSingleInput, ButtonPlusCreateNew, InputPearPass, InputPasswordPearPass, InputField, InputFieldPassword, InputSearch, etc.). That tree is legacy; the kit's Button takes variants.
4. Style with Tailwind utilities mapped to kit tokens — bg-surface-primary, text-text-primary, border-border-primary, etc. Use useTheme() / rawTokens only when a value is needed in JS. No hardcoded hex colors or px spacing for design-system values.
5. Icons come from the kit. @tetherto/pearpass-lib-ui-kit/icons has 133 icons. Do not add new SVGs under src/.
6. If the kit lacks something you need, stop and ask the user. Don't silently roll a custom component.

Component catalog (33 components)

Import pattern: import { ComponentName } from '@tetherto/pearpass-lib-ui-kit'

Actions

• Button — all CTAs. Takes variants; use instead of ButtonPrimary, ButtonSecondary, ButtonRoundIcon, ButtonLittle, ButtonFilter, ButtonFolder, ButtonSingleInput, ButtonCreate, ButtonPlusCreateNew.
• Pressable — low-level pressable wrapper for custom interactive elements.
• Link — text links.

Forms

• Form — form wrapper with validation.
• InputField — text input. Use instead of legacy InputPearPass / InputField.
• PasswordField — password input with strength indicator. Use instead of legacy InputPasswordPearPass / InputFieldPassword.
• SearchField — search input. Use instead of legacy InputSearch.
• SelectField — dropdown select. Use instead of legacy Select.
• Dropdown — low-level dropdown primitive.
• TextArea — multiline text input.
• Checkbox
• Radio — use instead of legacy RadioOption / RadioSelect.
• ToggleSwitch — use instead of legacy Switch / SwitchWithLabel.
• Slider
• DateField
• AttachmentField
• UploadField
• MultiSlotInput — split inputs for OTP / recovery codes. Use instead of custom OtpCodeField.
• FieldError — inline field validation error.

Typography

• Title — headings.
• Text — body text.

Layout / surfaces

• Dialog — modals. Use instead of custom ModalCard / ModalHeader / PopupCard wrappers.
• NativeBottomSheet — bottom sheets.
• PageHeader — top-of-page header.
• ItemScreenHeader — item-detail header.
• Breadcrumb
• ListItem
• NavbarListItem
• ContextMenu

Feedback

• AlertMessage — inline alerts.
• Snackbar — toast-style notifications.
• PasswordIndicator — standalone password strength meter.
• RingSpinner — loading spinner.

Type exports

• ThemeColors, Theme, ThemeType, RawTokens
• PasswordIndicatorVariant — 'vulnerable' | 'decent' | 'strong' | 'match'

Import types with import type { ... } from '@tetherto/pearpass-lib-ui-kit'.

Component props (15 most-used)

Required props have no ?. Always include a test ID on interactive components — see the "Test IDs" section below for which prop to use per component.

• Button — variant: 'primary' | 'secondary' | 'tertiary' | 'destructive', size: 'small' | 'medium', onClick, children, type?: 'button' | 'submit', disabled?, isLoading?, iconBefore?, iconAfter?, data-testid?. Icon-only buttons need aria-label.
• Dialog — title (ReactNode), onClose?, open?, footer?, children?, closeOnOutsideClick?, hideCloseButton?, trapFocus?, initialFocusRef?, testID?, closeButtonTestID?. Put action buttons in footer.
• InputField — label, value, onChange?: (e) => void, placeholder?, error?: string, inputType?: 'text' | 'password', disabled?, readOnly?, copyable?, onCopy?, leftSlot?, rightSlot?, testID?.
• PasswordField — label, value, onChange?, placeholder?, error?, passwordIndicator?: 'vulnerable' | 'decent' | 'strong' | 'match', infoBox?: string, copyable?, testID?.
• SearchField — value, onChangeText (yes, this one is still current), placeholderText?, size?: 'small' | 'medium', testID?.
• Form — children, onSubmit?, noValidate?, testID?. Wrap fields here; pair with useForm from @tetherto/pear-apps-lib-ui-react-hooks.
• Text — children, as?: 'p' | 'span', variant?: 'label' | 'labelEmphasized' | 'body' | 'bodyEmphasized' | 'caption', color?, numberOfLines?, data-testid?.
• Title — children, as?: 'h1' | 'h2' | ... | 'h6', data-testid?.
• AlertMessage — variant: 'info' | 'warning' | 'error', size: 'small' | 'medium' | 'big', title, description, actionText?, onAction?, testID?, actionTestId?.
• ToggleSwitch — checked?, onChange?: (b: boolean) => void, label?, description?, disabled?, data-testid?.
• Checkbox — same shape as ToggleSwitch (uses data-testid).
• Radio — options: Array<{value, label?, description?, disabled?}>, value?, onChange?: (v: string) => void, testID?.
• SelectField — label, value?, placeholder?, onClick? (opens dropdown), error?, disabled?, leftSlot?, rightSlot?, testID?.
• TextArea — value, onChange?, label?, placeholder?, error?, disabled?, testID?.
• Link — children, href?, isExternal?, onClick?, data-testid? (and standard <a> attributes).

For components not listed, open node_modules/@tetherto/pearpass-lib-ui-kit/dist/components/<Name>/types.d.ts.

Test IDs — testID vs data-testid

Always include a test ID on anything a user interacts with (buttons, fields, toggles, dialogs). Which prop depends on the component:

• testID — components that declare it explicitly: Dialog (+ closeButtonTestID), Form, InputField, PasswordField, SearchField, SelectField, TextArea, Radio, AlertMessage (+ actionTestId).
• data-testid — components that extend native HTML and don't redeclare it: Button, ToggleSwitch, Checkbox, Link, Pressable, Text, Title.

Rule of thumb: try testID first; if TypeScript rejects it, use data-testid. When editing an existing file, follow the naming pattern already there.

Prop naming — modern vs. deprecated (important)

The kit recently renamed several field props. Use the modern names in new code:

The deprecated props still work for now but will be removed.

Exception: SearchField still uses onChangeText + placeholderText — those aren't deprecated there. testID is current everywhere.

Styling

New UI is styled with Tailwind utility classes. The kit ships @tetherto/pearpass-lib-ui-kit/tailwind.css (already imported in src/index.css), which registers its color tokens with Tailwind v4's @theme inline. Standard utilities like bg-surface-primary, text-text-primary, border-border-primary therefore resolve against the design system and follow data-theme switches automatically. Tailwind is enabled in every UI build via the @tailwindcss/vite plugin in vite.config.main.js.

Prefer Tailwind classes for layout and static styling. Reach for useTheme() / rawTokens only when a value has to come from JS (e.g. a kit-component prop that takes a number, or a computed style).

<div className="bg-surface-primary border border-border-primary rounded-[8px] p-[24px] gap-[12px]">
  <Text className="text-text-primary">…</Text>
</div>

Kit color classes (from the kit's tailwind.css)

Usable with bg-*, text-*, border-* prefixes:

• Surfaces: background, surface-primary, surface-hover, surface-secondary, surface-elevated-on-interaction, surface-disabled, surface-destructive, surface-destructive-elevated, surface-error, surface-warning, surface-search-field
• Accents: primary, secondary, accent-hover, accent-active, focus-ring, on-primary
• Text (use with text-*): text-primary, text-secondary, text-tertiary, text-disabled, text-search-field, link-text — note these are the full token names, so the utility class is e.g. text-text-primary, text-link-text
• Borders (use with border-*): border-primary, border-secondary, border-search-field — utility is e.g. border-border-primary

Spacing / radius / font-size aren't auto-generated Tailwind utilities

The kit registers only color tokens with @theme inline. Spacing (--spacing2 … --spacing48), radius (--radius8 … --radius26), and font-size (--font-size12 … --font-size28) live on :root as CSS vars but don't produce Tailwind utility classes. Use them as arbitrary values — p-[var(--spacing24)], rounded-[var(--radius8)], text-[var(--font-size14)] — or pull from rawTokens in JS when needed.

rawTokens — flat, numeric-suffixed keys (not nested)

• Spacing: spacing2, spacing4, spacing6, spacing8, spacing10, spacing12, spacing16, spacing20, spacing24, spacing32, spacing40, spacing48 (all number, multiply with ${n}px)
• Radius: radius8, radius16, radius20, radius26
• Font size: fontSize12, fontSize14, fontSize16, fontSize24, fontSize28
• Font family: fontPrimary ("Inter"), fontDisplay ("Humble Nostalgia")
• Weight: weightRegular ("400"), weightMedium ("500")

theme.colors — common keys

colorSurfacePrimary, colorSurfaceHover, colorBorderPrimary, colorBorderSecondary, colorTextPrimary, colorTextSecondary, colorTextTertiary, colorLinkText. If you need one you haven't seen, inspect the ThemeColors type from @tetherto/pearpass-lib-ui-kit.

When hardcoded values are OK

Tokens cover the design-system primitives. Feature-specific layout values (a card's maxWidth: '500px', a one-off padding: '55px 0') are fine as literals — these aren't design tokens. Rule of thumb: if the value corresponds to a semantic design decision (spacing step, brand color, radius), it must come from a token.

Icons

import { Add, Download, Folder, OpenInNew } from '@tetherto/pearpass-lib-ui-kit/icons'

133 icons, mostly Material Design, with style variants as suffixes: Filled, Outlined, Round, Sharp, Tone (e.g. LockFilled, InfoOutlined, KeyboardArrowRightRound). If a name has no suffix, it exists as a single variant.

Commonly needed (check these first before browsing):

• Actions: Add, Download, ContentCopy, Share, Send, Swap, UploadFileFilled
• Folder / organization: Folder, FolderOpen, FolderCopy, CreateNewFolder, Layers
• Navigation / arrows: KeyboardArrowRightFilled, KeyboardArrowRightRound, KeyboardArrowLeftFilled, ExpandMore
• Status / feedback: InfoOutlined, ReportProblemRound, ErrorFilled, Check, DoneAll, CheckBox
• Security: LockFilled, Key, SecurityFilled, Fingerprint, TwoFactorAuthenticationFilled
• External / misc: ImportOutlined, OpenInNew

Discovering others: ls node_modules/@tetherto/pearpass-lib-ui-kit/dist/icons/components/ | grep -i <keyword> — names are PascalCase, grep is case-insensitive friendly.

Product-specific illustrations (e.g. src/shared/svgs/logoLock/) are not design-system icons and may stay under src/.

Anti-patterns to avoid

Do not:

• Add a new file under src/shared/components/ for a Button/Input/Modal variant.
• Import InputPearPass, InputPasswordPearPass, InputFieldPassword, any Button* variant, Switch / SwitchWithLabel, ModalCard / ModalHeader / PopupCard, OtpCodeField, RadioOption / RadioSelect, or Select from src/shared/components/ into any new file — swap to the kit equivalents.
• Add a V2 suffix to any file — the migration is complete and the suffix is permanently retired.
• Use native <button>, <input>, or <dialog> in production code (tests are fine).
• Hardcode hex colors, brand radii, or design-system spacing — use rawTokens and theme.colors. (Feature-specific layout literals like maxWidth: '500px' are fine.)
• Add new SVG files under src/ when the kit's icons subpath covers them.
• Introduce styled-components. Style with Tailwind utilities (plus rawTokens in JS when needed). styled-components is still in package.json but not used in src/ — keep it that way.

When the kit truly lacks something

1. Confirm by grepping node_modules/@tetherto/pearpass-lib-ui-kit/dist/components/ for the concept.
2. Check if a composition of existing kit primitives covers it (e.g. Pressable + Text + tokens).
3. If still missing, surface it to the user: "The kit doesn't export X — options are (a) compose from Y + Z, (b) request X be added upstream, (c) temporary local component. Which?" Do not silently create (c).