Frontend UI

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.