FRD: Consent and Cookies Library

Document Summary

Field	Details
Feature Name	Consent / Cookies Library
Status	Draft
Owner	David Holmes
Contributors	Engineering, Legal
Target Release	v2.0.0 (P2)
Related Links	Roadmap item #74
Last Updated	2026-05-26

Introduction

Overview

The Consent / Cookies library provides a complete consent management solution: a banner UI component, a preference model, analytics gating logic, and a persistence layer. Applications integrate it to collect, store, and enforce user consent choices in compliance with GDPR, CCPA, and similar regulations. All analytics and tracking scripts are gated on consent state, preventing execution until the user grants permission.

Goals

Provide a composable consent banner component with accept-all, reject-all, and customize options.
Model consent preferences as a typed, serializable structure with granular categories (necessary, analytics, marketing, functional).
Gate analytics and tracking script loading on consent state via a programmatic API.
Persist consent choices in cookies with configurable expiration and domain scope.
Support server-side consent checks for SSR applications.

Non-Goals

Implementing a full Consent Management Platform (CMP) with vendor tag management.
Providing legal advice or jurisdiction-specific consent text.
Managing individual cookie deletion (browser limitation).
Building an admin dashboard for consent analytics.

Scope

In Scope

Area	Description
Banner component	Accessible, dismissible consent banner with accept/reject/customize actions
Preference center	Modal or panel UI for granular category-level consent choices
Consent model	Typed `ConsentPreferences` with `necessary`, `analytics`, `marketing`, `functional` categories
Persistence	Cookie-based storage with configurable TTL and domain
Analytics gating	`isConsentGranted(category)` function and `ConsentGate` component for conditional rendering
SSR support	Server-side consent check from request cookies
React hook	`useConsent()` hook for reading and updating consent state
Mock/test utilities	Helpers for setting consent state in tests
Unit tests	Coverage of model, persistence, gating, and component behavior
Documentation	Storybook MDX docs with usage examples

Out of Scope

Area	Reason
Jurisdiction-specific legal text	Legal team provides copy; library provides slots
Tag management (GTM integration)	Consumer responsibility; library provides the gating signal
Cookie scanning / audit	Separate tooling concern
Consent analytics dashboard	Backend concern outside library scope
Geo-detection for consent requirements	Application-level concern

Users and Pain Points

User Groups

User	Description	Needs
Application developers	Engineers integrating consent management	A drop-in banner and gating API that works with minimal configuration
Legal / compliance	Team members ensuring regulatory compliance	Confidence that scripts are gated on consent and preferences are persisted correctly
End users	Website visitors	A clear, accessible way to manage cookie preferences
QA engineers	Testers verifying consent flows	Utilities for setting consent state in tests without UI interaction

Pain Points

User	Pain Point	Impact
Application developers	Each app builds its own consent banner with inconsistent behavior	Duplicated effort; inconsistent UX across products
Application developers	Analytics scripts load before consent is granted	Compliance risk; potential regulatory fines
Legal / compliance	No standardized preference model; each app stores consent differently	Difficult to audit; hard to prove compliance
End users	Consent banners are often inaccessible or confusing	Poor UX; users cannot effectively manage preferences

Definitions

Term	Definition
Consent category	A logical grouping of cookies/scripts: `necessary` (always allowed), `analytics`, `marketing`, `functional`
Consent banner	The initial UI prompting the user to accept, reject, or customize cookie preferences
Preference center	A detailed UI showing all consent categories with individual toggles
Analytics gating	The mechanism that prevents analytics/tracking scripts from loading until consent is granted
Consent cookie	The cookie storing the user’s serialized consent preferences

Current State

Existing Behavior

No shared consent management solution exists. Each application implements its own banner, storage, and gating logic.

Current Limitations

No standardized consent preference model across applications.
No shared banner component; each app builds its own with varying accessibility quality.
Analytics scripts often load unconditionally or rely on ad-hoc gating.
No SSR-compatible consent check; server-rendered pages cannot adapt to consent state.

Existing Workarounds

Developers copy consent banner implementations between projects.
Some apps use third-party CMP tools (OneTrust, CookieBot) but these are heavyweight and inconsistently configured.
Analytics gating is done with manual if checks scattered through initialization code.

Proposed Solution

Summary

Ship a TypeScript + React library (@dmwd/consent) providing a ConsentBanner component, a PreferenceCenter component, a ConsentProvider context, a useConsent() hook, cookie-based persistence, and an isConsentGranted() gating function.

Key Capabilities

ConsentBanner component with accept-all, reject-all, and customize buttons.
PreferenceCenter component with per-category toggles and save/cancel actions.
ConsentProvider wrapping the app to provide consent context.
useConsent() hook returning current preferences and update functions.
isConsentGranted(category) for programmatic checks (works on server and client).
ConsentGate component for conditionally rendering children based on consent.
Cookie persistence with configurable name, TTL, domain, and SameSite attribute.

User Experience

On first visit, users see a consent banner at the bottom of the viewport. They can accept all, reject all (keeping only necessary cookies), or open the preference center to choose categories individually. Their choice persists across sessions. Returning users see no banner unless consent has expired.

Developer Experience

Developers wrap their app in ConsentProvider, place ConsentBanner in their layout, and wrap analytics scripts in ConsentGate category="analytics". The useConsent() hook provides the current state for custom logic.

Requirements

ID	Requirement	Priority	Notes
FR-001	The library must export a `ConsentBanner` component	Must	Primary UI
FR-002	The library must export a `PreferenceCenter` component	Must	Granular control
FR-003	The library must export a `ConsentProvider` context	Must	State management
FR-004	The library must export a `useConsent()` hook	Must	Programmatic access
FR-005	The library must export an `isConsentGranted(category)` function	Must	Gating logic
FR-006	The library must export a `ConsentGate` component	Must	Declarative gating
FR-007	Consent must persist in cookies with configurable TTL	Must	GDPR requires re-consent
FR-008	The `necessary` category must always be enabled and not toggleable	Must	Legal requirement

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	`ConsentBanner` renders with accept-all, reject-all, and customize buttons	Users have clear choices	Must
FUNC-002	Clicking accept-all grants all categories and dismisses the banner	Quick opt-in	Must
FUNC-003	Clicking reject-all grants only `necessary` and dismisses the banner	Quick opt-out	Must
FUNC-004	Clicking customize opens the `PreferenceCenter`	Granular control	Must
FUNC-005	`PreferenceCenter` shows a toggle for each non-necessary category	Users can choose individually	Must
FUNC-006	`PreferenceCenter` has save and cancel actions	Users confirm or discard changes	Must
FUNC-007	`ConsentGate category="analytics"` renders children only when analytics consent is granted	Scripts are gated on consent	Must
FUNC-008	`useConsent()` returns `{ preferences, grantAll, rejectAll, updateCategory, hasConsented }`	Programmatic access to consent state	Must
FUNC-009	Banner does not render when user has already consented and consent has not expired	Returning users are not re-prompted	Must
FUNC-010	`isConsentGranted(category, cookieString?)` works server-side by parsing a cookie string	SSR support	Should

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Banner and preference center must meet WCAG 2.1 AA	Accessibility	Must
NFR-002	Consent cookie must use `Secure`, `SameSite=Lax`, and `HttpOnly` when possible	Security	Must
NFR-003	Banner must not cause layout shift (CLS)	Performance	Must
NFR-004	Library must work with React 18+ and React 19	Compatibility	Must
NFR-005	Bundle size under 8 KB minified + gzipped (excluding React)	Performance	Should
NFR-006	Consent state must be available within 1 render cycle of app mount	Performance	Must

API / Interface Requirements

Public API

Name	Type	Description	Required
`ConsentProvider`	`component`	Context provider; accepts `config` prop with cookie settings	Yes
`ConsentBanner`	`component`	Banner UI; accepts `privacyPolicyUrl`, `customizeLabel`, slot props for text	Yes
`PreferenceCenter`	`component`	Category toggles; accepts `categories` override for custom labels	Yes
`ConsentGate`	`component`	`{ category, children, fallback? }` — renders children when consent granted	Yes
`useConsent`	`hook`	Returns `{ preferences, grantAll, rejectAll, updateCategory, hasConsented, resetConsent }`	Yes
`isConsentGranted`	`function`	`(category: ConsentCategory, cookieString?: string) => boolean`	Yes
`ConsentPreferences`	`type`	`{ necessary: true; analytics: boolean; marketing: boolean; functional: boolean; consentedAt: string }`	Yes
`ConsentConfig`	`type`	`{ cookieName?: string; ttlDays?: number; domain?: string; sameSite?: string }`	Yes

Example Usage

import { ConsentProvider, ConsentBanner, ConsentGate } from "@dmwd/consent";

function App() {
  return (
    <ConsentProvider config={{ ttlDays: 365, domain: ".example.com" }}>
      <Layout>
        <ConsentGate category="analytics">
          <AnalyticsScript />
        </ConsentGate>
        <ConsentBanner privacyPolicyUrl="/privacy" />
      </Layout>
    </ConsentProvider>
  );
}

API Notes

ConsentPreferences.necessary is always true and cannot be set to false.
ConsentGate renders fallback (default: null) when consent is not granted.
resetConsent() clears the cookie and re-shows the banner.
Cookie value is JSON-serialized ConsentPreferences, base64-encoded.

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Banner must be a `role="dialog"` with `aria-label`	Announced to screen readers
A11Y-002	Banner must trap focus when open	Prevents interaction with content behind
A11Y-003	All interactive elements must be keyboard accessible	Tab, Enter, Space, Escape
A11Y-004	Escape key dismisses the preference center (not the banner)	Standard dialog behavior
A11Y-005	Toggle switches must have accessible labels including category name	Screen readers announce what each toggle controls
A11Y-006	Color contrast must meet WCAG 2.1 AA (4.5:1 for text)	All text and interactive elements
A11Y-007	Reduced motion: no entry/exit animations when `prefers-reduced-motion` is set	Respects user preference

Checklist

Keyboard support is defined.
Focus behavior is defined.
Screen reader behavior is defined.
Color contrast requirements are met.
Reduced motion behavior is considered.
Semantic HTML expectations are documented.
ARIA usage is defined only where needed.

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	API reference with all exported components, hooks, and types	Storybook MDX	Must
DOC-002	Quick start guide showing ConsentProvider + ConsentBanner setup	Storybook MDX	Must
DOC-003	Analytics gating guide with ConsentGate examples	Storybook MDX	Must
DOC-004	SSR guide showing `isConsentGranted` with cookie parsing	Storybook MDX	Should
DOC-005	Testing guide with consent state utilities	Storybook MDX	Must
DOC-006	Customization guide for banner text, styling, and categories	Storybook MDX	Should

Documentation Should Include

Overview and compliance context
Quick start setup
When to use (and when a full CMP is more appropriate)
Banner customization (text slots, styling)
Analytics gating patterns
SSR integration
Testing utilities
API reference
Common mistakes (e.g., loading scripts outside ConsentGate)

Dependencies

Dependency	Type	Owner	Status	Notes
React 18+	Engineering	David Holmes	Ready	Peer dependency
Design system tokens	Design	David Holmes	Ready	Colors, spacing, typography
None (other runtime)	—	—	Ready	Cookie persistence is self-contained

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Library does not provide legal text	Consumers must supply their own consent copy	Provide clear slots and example text in docs; document that legal review is required
Cookie-only persistence may not work with strict browser cookie policies	Some browsers block third-party cookies	Use first-party cookie with configurable domain; document limitations
Four fixed categories may not fit all apps	Some apps need more or fewer categories	Allow category override via config; default to the four standard categories
CLS from banner rendering	Banner appearing late causes layout shift	Render banner position in CSS before JS hydration; use fixed positioning
No geo-detection	Apps in single-jurisdiction deployments show banner unnecessarily	Library does not own geo-detection; consumer wraps ConsentProvider conditionally

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should the library support localStorage as an alternative to cookies for SPAs that do not need SSR consent checks?	David Holmes	Open	—
Q-002	Should we define a `ConsentEvent` type for analytics tracking of consent actions (granted, rejected, customized)?	David Holmes	Open	—
Q-003	Should the preference center support custom categories beyond the default four?	David Holmes	Open	—
Q-004	Should the banner support a “powered by” slot for CMP vendor attribution?	David Holmes	Open	—

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	`ConsentBanner` renders with accept-all, reject-all, and customize buttons	FUNC-001
AC-002	Clicking accept-all sets all categories to `true` and stores a consent cookie	FUNC-002
AC-003	Clicking reject-all sets only `necessary: true` and stores a consent cookie	FUNC-003
AC-004	`ConsentGate category="analytics"` renders children only when analytics consent is granted	FUNC-007
AC-005	`ConsentGate` renders `fallback` when consent is not granted	FUNC-007
AC-006	Banner does not render when a valid, non-expired consent cookie exists	FUNC-009
AC-007	`isConsentGranted("analytics", cookieString)` returns correct boolean from a cookie string	FUNC-010
AC-008	Banner has `role="dialog"` and traps focus	A11Y-001, A11Y-002
AC-009	All interactive elements are keyboard accessible	A11Y-003
AC-010	Unit tests pass covering all consent flows	FR-001 through FR-008
AC-011	Storybook MDX docs render without errors	DOC-001

LLM Handoff Instructions

Expected LLM Behavior

Follow the requirements and acceptance criteria in this document.
Do not expand scope beyond the In Scope section.
Respect the Out of Scope section.
Ask for clarification only when a requirement cannot be safely interpreted.
Prefer existing design system components and tokens over custom styles.
Banner should use design system color tokens, not hardcoded colors.
Use ConsentPreferences as a discriminated type with necessary: true as a literal.
Test consent cookie serialization and deserialization round-trips.

LLM Should Not

Invent undocumented product behavior.
Provide legal advice or jurisdiction-specific consent text.
Add third-party cookie management libraries.
Change unrelated components.
Use document.cookie directly outside the persistence module.
Implement geo-detection or jurisdiction routing.

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Four default consent categories (necessary, analytics, marketing, functional)	Covers the most common GDPR/CCPA categorization; extensible via config	David Holmes
2026-05-26	Cookie-based persistence (not localStorage)	Enables SSR consent checks; first-party cookies are widely supported	David Holmes
2026-05-26	Fixed positioning for banner to avoid CLS	Layout shift from a top/bottom banner is a common performance issue	David Holmes

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft