# 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. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/organization/Faq/Faq.tsx ## Guidance { "summary": "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.", "guidance": [ { "heading": "Overview", "body": "Question discovery in two presentations that share one `FaqItem` shape. This local preview\ndocuments the implemented web behavior. Vue, Swift and Kotlin implementations and platform\nparity have not been verified; the host owns answer copy and navigation." }, { "heading": "Faq.Carousel", "body": "A peeking horizontal strip of feature-toned cards for root screens. The whole card is the tap\ntarget; the question is the card's serif headline.\n\n**Card spec**\n\n- Card width `--cds-size-240`; aspect ratio `233 / 274` from the local stylesheet.\n- Card padding `--cds-space-24` top, `--cds-space-16` sides/bottom; radius `--cds-radius-md`.\n- Question ↔ arrow gap `--cds-space-16`; eyebrow ↔ question gap `--cds-space-12`.\n- Arrow badge `--cds-size-40` circle, `--cds-radius-full`, filled at 15% of the inverse text color.\n\n**Section spec**\n\n- The SectionHeader owns its heading padding; carousel inset is `20`, slide gap `12`.\n- Section bottom padding is `--cds-space-120`; the heading-to-carousel layout gap is `--cds-space-16`.\n- `fullBleed` spans the viewport width for a footer band that escapes a padded parent.\n\n**Tone mapping** — one `featureTone` colors the whole section. The class sits on the section so the\nbackdrop and every card inherit the hue:\n\n| featureTone | backdrop | card fill |\n| ------------ | ----------------------------------- | ------------------------------------ |\n| `monitoring` | `--cds-feature-monitoring-backdrop` | `--cds-feature-monitoring-container` |\n| `guard` | `--cds-feature-guard-backdrop` | `--cds-feature-guard-container` |\n| `identity` | `--cds-feature-identity-backdrop` | `--cds-feature-identity-container` |" }, { "heading": "Faq.List", "body": "A lower-emphasis vertical list for related-content footers, subordinate to the carousel. Rows are\n`List.Item`s (`size='sm'`) inside an inset grouped card (`--cds-bg-page`, `--cds-radius-lg`) so the\ngroup reads as a distinct, subordinate container." }, { "heading": "When to use which", "body": "- **Carousel** on a root/overview screen to surface common questions with emphasis.\n- **List** at the bottom of a detail screen to offer related questions without competing with the\n primary content.\n\nBoth leave navigation to the consumer: tapping fires `onQuestionSelect(id)`; the DS stays free of\nrouting so answer copy and detail screens live app-side." }, { "heading": "Props", "body": "`Faq.Carousel`\n\n`Faq.List` takes `items` (`FaqItem[]`), `onQuestionSelect(id)`, an optional `title` (defaults to\n\"Related questions\"), and an optional `testId`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/organization/Faq/Faq.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." } ## Contract and public API ```json { "props": [], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Faq", "public_path": "Faq", "import_path": "@cloakedinc/design-system", "root_kind": "namespace", "entrypoints": [ { "name": "Faq.Carousel", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/organization/Faq/FaqCarousel/FaqCarousel.tsx", "line": 15 }, "props_type": "FaqCarouselProps", "props": [ { "name": "items", "type": "FaqItem[]", "declared_type": "FaqItem[]", "required": true, "description": "Questions in scroll order. Later cards can be reached by native scrolling or keyboard Tab navigation; this presentation has no dots or arrows.", "source": { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 23 } }, { "name": "featureTone", "type": "\"monitoring\" | \"guard\" | \"identity\"", "declared_type": "FeatureTone", "required": true, "description": "Product-area hue applied to the backdrop and every card in the section.", "source": { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 25 }, "values": [ "guard", "identity", "monitoring" ], "values_complete": true }, { "name": "onQuestionSelect", "type": "(id: string) => void", "declared_type": "(id: string) => void", "required": true, "description": "Fires with the tapped card's `id`; the component keeps no selected state.", "source": { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 27 } }, { "name": "title", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Section heading. Defaults to \"Frequently Asked Questions\".", "source": { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 29 }, "default": "DEFAULT_TITLE", "default_kind": "source-expression" }, { "name": "fullBleed", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Spans the viewport width, escaping a padded parent, for a full-bleed footer band. To continue\nthe band color into the bottom over-pull, set `overscrollBottom` on the enclosing `Screen` to\nthe matching `var(--cds-feature--backdrop)`.", "source": { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 35 }, "values": [ false, true ], "values_complete": true, "default": "false", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 36 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Root selector; children derive as `-header`, `-carousel`, and `-card-`.", "source": { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 38 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" }, { "name": "Faq.List", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/organization/Faq/FaqList/FaqList.tsx", "line": 14 }, "props_type": "FaqListProps", "props": [ { "name": "items", "type": "FaqItem[]", "declared_type": "FaqItem[]", "required": true, "description": "Questions in row order. Each renders as a row title that wraps to two lines, then clamps.", "source": { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 47 } }, { "name": "onQuestionSelect", "type": "(id: string) => void", "declared_type": "(id: string) => void", "required": true, "description": "Fires with the tapped row's `id`; the whole row is the tap target.", "source": { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 49 } }, { "name": "title", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Section heading. Defaults to \"Related questions\".", "source": { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 51 }, "default": "DEFAULT_TITLE", "default_kind": "source-expression" }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Root selector; the list and its rows derive from it as `-list` and `-row-`.", "source": { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 53 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 8, "name": "FaqItem", "code": "export interface FaqItem {\n /** Handed back by `onQuestionSelect` so the app can resolve its own answer copy and actions. Also the `-card-` / `-row-` selector suffix. */\n id: string;\n /** The question copy, shown as the card's serif headline and the tap target's accessible name. */\n question: string;\n /** Optional eyebrow label grouping the question (e.g. \"Getting Started\"). */\n category?: string;\n}" }, { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 21, "name": "FaqCarouselProps", "code": "export interface FaqCarouselProps {\n /** Questions in scroll order. Later cards can be reached by native scrolling or keyboard Tab navigation; this presentation has no dots or arrows. */\n items: FaqItem[];\n /** Product-area hue applied to the backdrop and every card in the section. */\n featureTone: FeatureTone;\n /** Fires with the tapped card's `id`; the component keeps no selected state. */\n onQuestionSelect: (id: string) => void;\n /** Section heading. Defaults to \"Frequently Asked Questions\". */\n title?: string;\n /**\n * Spans the viewport width, escaping a padded parent, for a full-bleed footer band. To continue\n * the band color into the bottom over-pull, set `overscrollBottom` on the enclosing `Screen` to\n * the matching `var(--cds-feature--backdrop)`.\n */\n fullBleed?: boolean;\n className?: string;\n /** Root selector; children derive as `-header`, `-carousel`, and `-card-`. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/components/organization/Faq/types.ts", "line": 45, "name": "FaqListProps", "code": "export interface FaqListProps {\n /** Questions in row order. Each renders as a row title that wraps to two lines, then clamps. */\n items: FaqItem[];\n /** Fires with the tapped row's `id`; the whole row is the tap target. */\n onQuestionSelect: (id: string) => void;\n /** Section heading. Defaults to \"Related questions\". */\n title?: string;\n /** Root selector; the list and its rows derive from it as `-list` and `-row-`. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/styles/featureTone.ts", "line": 9, "name": "FEATURE_TONES", "code": "FEATURE_TONES = ['monitoring', 'guard', 'identity'] as const" }, { "path": "packages/design-system/src/styles/featureTone.ts", "line": 11, "name": "FeatureTone", "code": "export type FeatureTone = (typeof FEATURE_TONES)[number];" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Faq", "status": "preview", "version": "0.1.0-preview.1", "summary": "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." }, "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 } ], "allowedDesignChoices": { "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": {}, "featureTones": { "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": [], "measurements": [ { "id": "card-width", "label": "Card width", "kind": "exact", "token": "--cds-size-240", "value": 240, "unit": "px", "appliesTo": [ "question" ] }, { "id": "card-proportion", "label": "Card aspect ratio", "kind": "exact", "value": "233 / 274", "unit": "ratio", "appliesTo": [ "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", "appliesTo": [ "question" ] }, { "id": "card-inline-inset", "label": "Card inline and bottom inset", "kind": "exact", "token": "--cds-space-16", "value": 16, "unit": "px", "appliesTo": [ "question" ] }, { "id": "section-gap", "label": "Heading-to-carousel layout gap", "kind": "exact", "token": "--cds-space-16", "value": 16, "unit": "px", "appliesTo": [ "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", "appliesTo": [ "container" ] }, { "id": "carousel-inset", "label": "Carousel edge inset", "kind": "exact", "token": "--cds-space-20", "value": 20, "unit": "px", "appliesTo": [ "container" ] }, { "id": "carousel-gap", "label": "Carousel card gap", "kind": "exact", "token": "--cds-space-12", "value": 12, "unit": "px", "appliesTo": [ "container" ] }, { "id": "arrow-diameter", "label": "Arrow badge diameter", "kind": "exact", "token": "--cds-size-40", "value": 40, "unit": "px", "appliesTo": [ "arrow" ] }, { "id": "card-radius", "label": "Carousel card radius", "kind": "exact", "token": "--cds-radius-md", "value": 16, "unit": "px", "appliesTo": [ "question" ] }, { "id": "list-radius", "label": "Grouped list radius", "kind": "exact", "token": "--cds-radius-lg", "value": 20, "unit": "px", "appliesTo": [ "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." ] }, "typographyAndColor": { "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." } ], "contentAdaptation": [ { "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." } ], "motionHaptics": { "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." } ] }, "platformDifferences": [ { "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." } ] }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "tokens": [ { "name": "--cds-size-240", "light": "240px", "dark": "240px" }, { "name": "--cds-space-24", "light": "24px", "dark": "24px" }, { "name": "--cds-space-16", "light": "16px", "dark": "16px" }, { "name": "--cds-space-120", "light": "120px", "dark": "120px" }, { "name": "--cds-space-20", "light": "20px", "dark": "20px" }, { "name": "--cds-space-12", "light": "12px", "dark": "12px" }, { "name": "--cds-size-40", "light": "40px", "dark": "40px" }, { "name": "--cds-radius-md", "light": "16px", "dark": "16px" }, { "name": "--cds-radius-lg", "light": "20px", "dark": "20px" }, { "name": "--cds-type-h3-serif-size", "light": "1.5rem", "dark": "1.5rem" }, { "name": "--cds-type-h4-size", "light": "1.25rem", "dark": "1.25rem" }, { "name": "--cds-type-body-small-size", "light": "0.875rem", "dark": "0.875rem" }, { "name": "--cds-text-inverse", "light": "#ffffff", "dark": "#ffffff" }, { "name": "--cds-bg-page", "light": "#f3f1ed", "dark": "#141410" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-feature-monitoring-container", "light": "#2c5a3d", "dark": "#2c5a3d" }, { "name": "--cds-radius-full", "light": "9999px", "dark": "9999px" }, { "name": "--cds-feature-monitoring-backdrop", "light": "#193524", "dark": "#193524" }, { "name": "--cds-feature-guard-backdrop", "light": "#112a3d", "dark": "#112a3d" }, { "name": "--cds-feature-guard-container", "light": "#1b4566", "dark": "#1b4566" }, { "name": "--cds-feature-identity-backdrop", "light": "#251b3d", "dark": "#251b3d" }, { "name": "--cds-feature-identity-container", "light": "#3d2e66", "dark": "#3d2e66" } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": null, "spec_origin": "local-authored", "local_spec_source_status": "preview", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ] } ``` ## Visual states - [Monitoring](/storybook/iframe.html?id=cloaked-design-system-organization-faq--monitoring&viewMode=story) | export: Monitoring | source: packages/design-system/src/components/organization/Faq/Faq.stories.tsx - [Guard](/storybook/iframe.html?id=cloaked-design-system-organization-faq--guard&viewMode=story) | export: Guard | source: packages/design-system/src/components/organization/Faq/Faq.stories.tsx - [Identity](/storybook/iframe.html?id=cloaked-design-system-organization-faq--identity&viewMode=story) | export: Identity | source: packages/design-system/src/components/organization/Faq/Faq.stories.tsx - [Without Categories](/storybook/iframe.html?id=cloaked-design-system-organization-faq--without-categories&viewMode=story) | export: WithoutCategories | source: packages/design-system/src/components/organization/Faq/Faq.stories.tsx - [Related List](/storybook/iframe.html?id=cloaked-design-system-organization-faq--related-list&viewMode=story) | export: RelatedList | source: packages/design-system/src/components/organization/Faq/Faq.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.