Card
Content sections and focused statistics on shared surfaces.
Installation
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"Import @commenda/pathfinder/styles.css once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from @commenda/pathfinder/card. Interactive callbacks belong in a client component in Next.js App Router.
API reference
| Prop | Type | Behavior |
|---|---|---|
childrenRequired | ReactNode | Required section body |
headerConfig | CardHeaderConfigView fields | Optional; heading level defaults to 3 |
footerConfig | CardFooterConfigView fields · 2 shapes | At least one action required |
elevation | "flat"|"raised" | raised |
padding | "default"|"none" | default: 16 body padding |
scrollConfig | ObjectView fields | Optional explicit, named scrolling region |
id | string | Stable HTML identifier for the component. |
className | string | Additional classes for the component root. |
headerConfigObject fields
| Field | Type | Requirement |
|---|---|---|
title | string | Required |
description | string | Optional |
headingLevel | 2 | 3 | 4 | 5 | 6 | Optional |
actionConfig | FeedbackAction | Optional |
scrollConfigObject fields
| Field | Type | Requirement |
|---|---|---|
maxHeight | NonNullable<Property.MaxHeight<string | number> | undefined> | Required |
label | string | Required |
Root IDs, className, appropriate ARIA attributes, and typed refs are supported.
Usage rules
Card keeps an arbitrary table, list, or form body as children, with direct header/footer configs. Header/footer actions use the established FeedbackAction contract: a label and either onClick or href. Primary and secondary action appearance follows the component design. Do not wrap a form/table in a card-wide link.
Body content grows naturally unless scrollConfig is supplied. It becomes a keyboard-reachable scrolling region when it actually overflows. The authored Figma examples contain different height caps; none is imposed globally. Raised cards sit on the canvas, flat cards sit within another surface.
StatCard
| Prop | Type | Default / behavior |
|---|---|---|
| label | string | Required metric label |
| value | string or number | Required; zero is preserved |
| meta | string | Optional comparison/context |
| changeConfig | { label: string; tone: BadgeTone } | Optional change Badge |
| elevation | raised or flat | raised |
| linkConfig | { href; target?; rel?; render? } | Optional native-link behavior |
The application formats currency/numbers and determines whether a change is positive: a negative cost change can be good. Only linked StatCards have a hover affordance. A static section Card remains a content container. Neither component fetches data or hides arbitrary children behind a fabricated loading state.
Examples
Flat
Footer
Scrolling
Stats
Design rules
Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.
Card and StatCard
Source: 938:223, section 938:6, stat 938:182, padding-none 942:38. The Card documentation frame contains placeholder text; it is not a source of confirmed guidance.
SURFACE-CARD-01— Source: white, 0.5 pearl-300 border, radius12. Raised on canvas, flat within surfaces. Section header title/description/one action, divider, body, optional footer. Header padding12/16/12; body16 or none. No arbitrary dashboard/business behavior.SURFACE-CARD-02— Pathfinder: natural body height by default. scrollConfig explicitly supplies maxHeight and region label; overflow becomes keyboard reachable. Caller-supplied dimensions are an intentional inline-style exception, not additional design tokens.SURFACE-CARD-03— Source/Pathfinder: static cards have no hover affordance. Section actions remain individual buttons/anchors; no card-wide anchor around arbitrary forms/tables. Footer config requires at least one action, using the existing FeedbackAction contract.SURFACE-CARD-04— Source/Pathfinder: StatCard is a separate small API with shared surface styles, padding16/gap8/Heading24 and optional Badge change. App formats values and chooses change meaning. linkConfig alone enables native navigation and authored hover/focus behavior; zero is a valid value.