Cloaked Design SystemOrganization

Faq

Question discovery in a feature-toned card carousel or a related-question list. The host owns answers and navigation; this family exposes Faq.Carousel and Faq.List, not a callable Faq root.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

5 stories

Monitoring selectedOpen canvas

Example source

packages/design-system/src/components/organization/Faq/Faq.stories.tsxExport Monitoring

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

Question discovery in a feature-toned card carousel or a related-question list. The host owns answers and navigation; this family exposes Faq.Carousel and Faq.List, not a callable Faq root.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 2 entry points · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Faq } from '@cloakedinc/design-system';

Faq.CarouselFaqCarouselProps

packages/design-system/src/components/organization/Faq/FaqCarousel/FaqCarousel.tsx:15

Prop	Type	Presence	Notes
`items`	`FaqItem[]`	Required	Questions in scroll order. Later cards can be reached by native scrolling or keyboard Tab navigation; this presentation has no dots or arrows.
`featureTone`	`"monitoring" \| "guard" \| "identity"`	Required	Product-area hue applied to the backdrop and every card in the section.
`onQuestionSelect`	`(id: string) => void`	Required	Fires with the tapped card's `id`; the component keeps no selected state.
`title`	`string \| undefined`	Optional	Section heading. Defaults to "Frequently Asked Questions".Source default: `DEFAULT_TITLE`
`fullBleed`	`boolean \| undefined`	Optional	Spans the viewport width, escaping a padded parent, for a full-bleed footer band. To continue the band color into the bottom over-pull, set `overscrollBottom` on the enclosing `Screen` to the matching `var(--cds-feature-<tone>-backdrop)`.Source default: `false`
`className`	`string \| undefined`	Optional
`testId`	`string \| undefined`	Optional	Root selector; children derive as `-header`, `-carousel`, and `-card-<item id>`.

Faq.ListFaqListProps

packages/design-system/src/components/organization/Faq/FaqList/FaqList.tsx:14

Prop	Type	Presence	Notes
`items`	`FaqItem[]`	Required	Questions in row order. Each renders as a row title that wraps to two lines, then clamps.
`onQuestionSelect`	`(id: string) => void`	Required	Fires with the tapped row's `id`; the whole row is the tap target.
`title`	`string \| undefined`	Optional	Section heading. Defaults to "Related questions".Source default: `DEFAULT_TITLE`
`testId`	`string \| undefined`	Optional	Root selector; the list and its rows derive from it as `-list` and `-row-<item id>`.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

The FAQ organism, in two presentations that share one FaqItem shape. This page is the cross-platform spec — iOS and Android should mirror the dimensions, spacing, and tone mapping below so the pattern reads the same on every surface.

Faq.Carousel

A peeking horizontal strip of feature-toned cards for root screens. The whole card is the tap target; the question is the card's serif headline.

Card spec

Card width --cds-size-240; aspect ratio 233 / 274 (the Figma card proportion).
Card padding --cds-space-24 top, --cds-space-16 sides/bottom; radius --cds-radius-md.
Question ↔ arrow gap --cds-space-16; eyebrow ↔ question gap --cds-space-12.
Arrow badge --cds-size-40 circle, --cds-radius-full, filled at 15% of the inverse text color.

Section spec

Title (Text h4) padded --cds-space-20 inline; carousel inset 20, slide gap 12.
Section padding --cds-space-32 top, --cds-space-120 bottom; gap --cds-space-24.
fullBleed spans the viewport width for a footer band that escapes a padded parent.

Tone mapping — one featureTone colors the whole section. The class sits on the section so the backdrop and every card inherit the hue:

featureTone	backdrop	card fill
`monitoring`	`--cds-feature-monitoring-backdrop`	`--cds-feature-monitoring-container`
`guard`	`--cds-feature-guard-backdrop`	`--cds-feature-guard-container`
`identity`	`--cds-feature-identity-backdrop`	`--cds-feature-identity-container`

Faq.List

A lower-emphasis vertical list for related-content footers, subordinate to the carousel. Rows are List.Items (size='sm') inside an inset grouped card (--cds-bg-page, --cds-radius-lg) so the group reads as a distinct, subordinate container.

When to use which

Carousel on a root/overview screen to surface common questions with emphasis.
List at the bottom of a detail screen to offer related questions without competing with the primary content.

Both leave navigation to the consumer: tapping fires onQuestionSelect(id); the DS stays free of routing so answer copy and detail screens live app-side.

Props

Faq.Carousel

Faq.List takes items (FaqItem[]), onQuestionSelect(id), an optional title (defaults to "Related questions"), and an optional testId.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: heading
Label: Section heading
Description: Names the question group and its carousel region or list.
Required: true

Id: question
Label: Question target
Description: A whole card or row sends the question id to the host on activation.
Required: true

Id: category
Label: Category
Description: Optional eyebrow on carousel cards; list rows show the question only.
Required: false

Id: arrow
Label: Directional marker
Description: Decorative arrow signals navigation on cards; row disclosure comes from List.Item.
Required: false

Id: container
Label: Question group
Description: A horizontal snap strip or a vertical list preserves input order.
Required: true

Allowed Design Choices

Variants

Carousel

Label: Faq.Carousel
Description: Higher-emphasis feature-toned footer band with peeking cards.

List

Label: Faq.List
Description: Lower-emphasis related questions in a grouped page surface.

Sizes

Feature Tones

Monitoring

Label: Monitoring

Guard

Label: Guard

Identity

Label: Identity

Variants

Id: carousel
Label: Carousel
Description: Call Faq.Carousel with items, featureTone and onQuestionSelect.
Platforms: web

Id: list
Label: List
Description: Call Faq.List with items and onQuestionSelect. These are composition members, not a variant prop.
Platforms: web

Sizes

None specified

Measurements

Id: card-width
Label: Card width
Kind: exact
Token: --cds-size-240
Value: 240
Unit: px
Applies To: question

Id: card-proportion
Label: Card aspect ratio
Kind: exact
Value: 233 / 274
Unit: ratio
Applies To: question
Notes: Recorded from local CSS; this value does not establish a verified Figma revision.

Id: card-top-inset
Label: Card top inset
Kind: exact
Token: --cds-space-24
Value: 24
Unit: px
Applies To: question

Id: card-inline-inset
Label: Card inline and bottom inset
Kind: exact
Token: --cds-space-16
Value: 16
Unit: px
Applies To: question

Id: section-gap
Label: Heading-to-carousel layout gap
Kind: exact
Token: --cds-space-16
Value: 16
Unit: px
Applies To: container
Notes: SectionHeader owns additional heading padding; this is the current Faq section gap.

Id: section-bottom-inset
Label: Carousel band bottom inset
Kind: exact
Token: --cds-space-120
Value: 120
Unit: px
Applies To: container

Id: carousel-inset
Label: Carousel edge inset
Kind: exact
Token: --cds-space-20
Value: 20
Unit: px
Applies To: container

Id: carousel-gap
Label: Carousel card gap
Kind: exact
Token: --cds-space-12
Value: 12
Unit: px
Applies To: container

Id: arrow-diameter
Label: Arrow badge diameter
Kind: exact
Token: --cds-size-40
Value: 40
Unit: px
Applies To: arrow

Id: card-radius
Label: Carousel card radius
Kind: exact
Token: --cds-radius-md
Value: 16
Unit: px
Applies To: question

Id: list-radius
Label: Grouped list radius
Kind: exact
Token: --cds-radius-lg
Value: 20
Unit: px
Applies To: container

Layout

Alignment: Heading and first carousel card share a 20px edge inset; related questions fill the list width.
Flow: Carousel cards run horizontally in supplied order. Related questions stack vertically under their heading.
Notes: fullBleed expands only Faq.Carousel to the viewport width and escapes parent inline padding.
Faq.List uses compact rows with a two-line question clamp. Its grouped container adds 4px block and 16px inline padding.
The carousel has no controls, dots or autoplay exposed by Faq. Those underlying Carousel features retain their disabled defaults.

Typography And Color

Typography

Label: Carousel question
Description: Uses the h3-serif ramp.
Token: --cds-type-h3-serif-size

Label: Related question heading
Description: Uses the h4 ramp rendered as an h2.
Token: --cds-type-h4-size

Label: Category
Description: Uses the body-small ramp at 0.75 opacity.
Token: --cds-type-body-small-size

Colors

Label: Carousel text
Description: Uses inverse text over the chosen feature backdrop and container.
Token: --cds-text-inverse

Label: Related list surface
Description: Rows and grouped container use the page background.
Token: --cds-bg-page

Label: Related question text
Description: Uses primary text on the page surface.
Token: --cds-text-primary

Label: Monitoring container
Description: One example of the three explicit feature-tone pairings.
Token: --cds-feature-monitoring-container

States

Id: default
Label: Default
Description: Items render in input order with no question selected by this family.

Id: pressed
Label: Pressed
Description: A card or row provides its press treatment and calls onQuestionSelect with the item id.

Id: empty
Label: Empty items
Description: The section heading and container remain; no loading or empty-state message is synthesized.

Id: long-question
Label: Long question
Description: List questions clamp to two lines. Card questions wrap within a fixed-width aspect-ratio card; verify long or translated copy.

Behavior

Label: Host-owned navigation
Description: The same required onQuestionSelect(id) callback serves both presentations. The component does not fetch answers, navigate, create routes or store a chosen question.

Label: Stable identity
Description: Provide a stable unique id and a meaningful question for each item. The id is also used for React keys and test selector suffixes.

Label: No synthetic loading contract
Description: Faq exposes no disabled, pending, success or error props. Loading and error presentations belong to the host until a reviewed API is introduced.

Accessibility

Label: Names and headings
Description: Visible category and question text form a card button name; the arrow is hidden from assistive technology. Faq.List uses an h2 and a named List; Faq.Carousel uses the SectionHeader heading and names the Carousel region.

Label: Visible keyboard focus
Description: Cards and rows inherit the shared focus-visible outline. Its inset offset keeps the indicator inside clipped card and list containers; component-specific focus treatments may override this default.

Label: Carousel reachability
Description: Every question card remains in the accessibility tree and keyboard tab order. Native scrolling or Tab navigation reaches later cards; Enter activates the focused question. Faq has no next/previous controls. The shared Carousel pauses any autoplay while focus is inside, although Faq does not enable autoplay.

Label: Do not nest controls
Description: Keep question content textual and avoid nested interactive content inside a card or row target.

Content Adaptation

Label: Questions, not answers
Description: Keep answer copy, links and item-specific actions outside this component. Use recognizable questions that explain the destination.

Label: Content stress cases
Description: Review long translations, large text, empty arrays, duplicate ids and narrow viewports. Do not infer tested support from this preview specification.

Motion Haptics

Motion

Label: User-triggered only
Description: Faq does not enable Carousel autoplay. Card and row presses use the shared fast press transform; reduced-motion removes that transform, while opacity feedback remains.

Haptics

Label: Host configuration
Description: Cards request selection feedback; list rows request light feedback. Delivery depends on CdsProvider haptic configuration and environment support; no native behavior is verified.

Platform Differences

Platforms: ios
android
Description: Native implementations and platform parity are not verified. Vue also has no local implementation.
Rationale: This preview was authored from the local React types, implementation, styles and documentation. Native unit, typography, interaction and accessibility mappings require platform review.

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1