frontend-ui

name: frontend-ui description: Map of reusable UI components and the design system (Chakra UI v3) in apps/frontend. Catalogs existing components so new code reuses them instead of duplicating, and documents semantic tokens, recipe variants, and style patterns (mobile-first, modal/bottom-sheet split, textStyle, semantic colors). Use when building or editing anything under apps/frontend/src/, when asked to add a page/component/modal/card/form/button, when writing Chakra JSX, when choosing colors/spacing/typography, or when touching apps/frontend/src/app/theme/. Triggers on frontend, UI, component, reusable, Chakra, Chakra v3, theme, recipe, slot recipe, textStyle, semantic color, design token, design system, variant, card, button, modal, bottom sheet, drawer, badge, input, form, empty state, step card, stat card, mobile-first, colorPalette, bg.primary, text.default.

Frontend UI (Chakra v3) — Components & Style Map

Before writing any UI under apps/frontend/src/, check this catalog. Reuse existing components; never re-invent a modal, card, button, or form field that already exists.

1. Where the design system lives

• apps/frontend/src/app/theme/theme.ts — createSystem config, tokens, semanticTokens, textStyles, keyframes, recipes registry.
• apps/frontend/src/app/theme/*.ts — one file per recipe / slot recipe (button.ts, card.ts, badge.ts, input.ts, alert.ts, dialog.ts, tabs.ts, text.ts, heading.ts, steps.ts, switch.ts, table.ts, checkbox.ts, radio-group.ts, popover.ts, select.ts, native-select.ts, skeleton.ts, separator.ts, breadcrumb.ts).
• CSS vars prefix: vbd (e.g. var(--vbd-colors-...)).
• After ANY theme change: yarn chakra:typegen (or yarn chakra:typegen:watch in dev).

2. Design tokens — use these, never hex

Typography

Never set fontSize or lineHeight directly. For responsive sizes use { base: "sm", md: "md" }.

Semantic colors (use these in color, bg, borderColor)

Raw palettes (gray/blue/red/green/orange 50-950) exist but prefer semantic tokens so dark mode works automatically.

Recipe variants (cheat sheet)

For anything not covered above, open the recipe file in app/theme/ and check its variants. If you need a new variant, add it there (one concern per file) rather than inline styles in JSX.

3. Reusable component catalog

Paths are relative to apps/frontend/src/. Search these before creating anything new.

Shells: modals, drawers, bottom sheets

Cards & containers

Identity, addresses & avatars

Forms & inputs (under components/CustomFormFields/)

Navigation, layout, feedback

Chakra v3 primitives (under components/ui/, generated by CLI)

clipboard.tsx, color-mode.tsx, empty-state.tsx, provider.tsx, toaster.tsx, toggle-tip.tsx, tooltip.tsx. Import from @/components/ui/<name>. Use toaster (not a custom toast), Tooltip (not a custom one).

Icons

• Prefer react-icons (react-icons/lu for Lucide is the house standard; react-icons/fa6 used too, plus iconoir-react).
• Custom icons live in components/Icons/ as React components wrapping SVGs under components/Icons/svg/. Wrap with Chakra <Icon as={MyIcon} boxSize={4} /> — never import the SVG multiple times to recolor.
• Key branded icons: B3TRIcon, VOT3Icon, VETIcon, VTHOIcon, LeafIcon, Handshake, OkHandIcon, SignIcon, WalletIcon, VoteCheckmarkIcon, BeBetterVeBetterIcon, ThreeSparklesIcon, ThreeTokensIcon, CurveArrowIcon, ExclamationTriangle.

Domain-specific feature dirs (don't duplicate their internals)

Activities/*, AllocationAmounts/*, AllocationRoundsList/*, AllocationStateBadge/*, AssetsOverview/*, Convert/* (swap modal + token pickers), CreateEditAppForm/*, FreshDeskWidget/*, GmNFT/*, Leaderboard/*, PowerUpModal/*, Proposal/* (+ ProposalStatusBadge, ResultsDisplay), ProposalExecutableActions/*, ProposalSessionSection/*, ProposalSupportProgressChart/*, Sustainability/*, SubmitCreatorForm/*, GenerateFunctionToCallParamsInput/*.

4. Style patterns to replicate

Mobile-first (~90% of users are mobile)

Always write base styles first, add md/lg for larger screens:

<Text textStyle={{ base: "sm", md: "md" }} color="text.subtle">...</Text>
<Card.Body p={{ base: "4", md: "6" }}>...</Card.Body>

Prefer SimpleGrid/Grid over deep HStack/VStack nesting. Cap heading clamping with lineClamp. Ensure touch targets ≥ 44px and no horizontal overflow at 360px wide.

Modal vs bottom sheet

Always wrap dialogs in BaseModal. It renders <Dialog> on desktop (≥1060px) and <BaseBottomSheet> on mobile. Don't hand-roll breakpoint-switched dialogs.

Cards

• Listing card → <Card.Root variant="outline"> + <Card.Body> + optional <Card.Footer>.
• Info tile → StatCard with variant="info|warning|positive|neutral", backgrounds come from status.{variant}.{subtle|secondary}.
• Empty state → always EmptyStateCard with a Lucide/iconoir icon.
• Internal gray sub-panels → bg="bg.secondary" + borderRadius="xl" + p={3} (see ChallengeCard prize/stats panel).

Buttons

• Primary CTA → <Button variant="primary"> (filled blue).
• Secondary CTA → variant="secondary" (tinted blue).
• Outline/tertiary → variant="tertiary".
• Destructive → variant="negative".
• Link-style → variant="link".
• Icon-only → wrap Chakra <IconButton> with the same variants; set colorPalette for semantic hues (e.g. colorPalette="gray" for neutral).

Text color conventions

• Primary copy: omit color (inherits text.default).
• Secondary/hint copy: color="text.subtle".
• Uppercase eyebrows: textTransform="uppercase" + color="gray.500" (see StepCard).
• Numeric emphasis: fontWeight="bold" + color="brand.primary".

Badges for state

Use <Badge variant="..."> with the status palette (positive, negative, warning, info, neutral, etc.). Domain badges (ChallengeStatusBadge, ProposalStatusBadge, AllocationStateBadge, GrantsProposalStatusBadge) already map enum → variant — use them.

Links & navigation

• Internal links: Chakra <Link> (variants underline, plain, ghost) or Next's Link when routing; for card-wide links use <LinkBox> + <LinkOverlay>.
• Route navigation inside handlers: const router = useRouter(); router.push("/path").

Loading & skeletons

• Prefer Chakra <Skeleton loading={...}> wrapping the actual content (see StatCard).
• For list pages, build a dedicated *Skeleton.tsx sibling (see ChallengesPageSkeleton, CompactSkeleton).

i18n

Every user-facing string goes through useTranslation().t(...) using the English phrase as the key (per frontend-i18n-keys rule). After adding a key, use the translate skill to sync all 15 locale files. Interpolations: t("Round #{{roundId}} completed", { roundId }).

Accessibility & data-cy

• Give actionable elements data-cy="kebab-case-id" (see AddressButton) for e2e tests.
• Icons inside clickable buttons get aria-label.
• Dialogs set ariaTitle / ariaDescription (already handled by BaseModal).

5. Contract hooks inside UI

Use useCallClause from @vechain/vechain-kit (see root CLAUDE.md). Do not use deprecated useConnex. Read-side hooks live in api/contracts/; write-side (clause-building + tx lifecycle) in feature api/*/useXActions.ts.

6. Keeping this skill current

This is a living map. Update it in the same commit whenever you:

1. Add / rename / delete a shared component in apps/frontend/src/components/ — add/remove it from the correct table in §3.
2. Add / remove a recipe variant in apps/frontend/src/app/theme/*.ts — update the cheat-sheet table in §2.
3. Add / remove / rename a semantic token in theme.ts — update the semantic-colors table in §2.
4. Introduce a new house pattern (e.g. a new modal shell, a new toast, a new listing skeleton) — document it in §4.
5. Deprecate a legacy component — move it to a "deprecated — use X instead" line in its row.

Rules to respect when editing this file:

• Keep it under 500 lines.
• Prefer updating existing tables over appending new sections.
• Match terminology with the codebase (textStyle, variant, colorPalette, recipe, slot recipe).
• Don't document app-feature-specific internals here — feature-specific details belong in their own skill (e.g. challenges).
• Don't paste implementation code; link to the file path and describe the shape.

Sanity checks (run mentally before saving):

• Every component listed has a verifiable path.
• No hex colors in examples (use semantic tokens).
• No fontSize/lineHeight in examples (use textStyle/size).
• Examples are mobile-first.