feat(card-container): add visual container atom

[egdev6]

Summary

• Adds the CardContainer atom as a visual, non-interactive container with the project 6-file component pattern.
• Exposes surface, padding, radius, hover, and floating glass backdropBlur variants backed by design tokens.
• Adds Storybook/docs coverage, including a focused backdropBlur story over a single gray block to compare sm, md, and lg.

Closes #17

Review scope

• Primary files/areas: src/components/atoms/card-container/*, src/styles/theme.css, src/index.ts, component/design docs.
• Out of scope: unrelated component behavior beyond the pre-existing React ref type fix needed for build.
• Review workload: large (~600 changed lines) because this adds a full atom, tests, stories, tokens, and docs. Fresh reviewer passes found no blockers.

Type of change

• New component
• Existing component update/refactor
• Bug fix
• Accessibility
• Design tokens
• Storybook/docs
• Infrastructure/tooling
• NPM/dependencies

Workflow gates

• Linked issue is present with Closes #NNN or maintainer approved an exception.
• Linked issue has label status:approved before implementation starts.
• Work was started through the Project flow: assignee set, Project status In progress, branch/worktree recorded.
• PR title follows Conventional Commit format: <type>(<optional scope>): <description>.
• Commits follow the same commitlint-enforced format.
• Diff is focused; unrelated work is called out in Review scope.
• MCP/runtime artifacts are absent: .playwright-mcp, page-*.png, page-*.jpeg, *.md.playwright-output.

Component evidence (required for component changes)

• Validated component spec is linked or quoted in the issue.
• Accessibility contract from the spec was implemented or deviations are explained below.
• Follows the 6-file pattern: types.ts, use*.ts, Component.tsx, Component.test.tsx, Component.stories.tsx, index.ts.
• CVA variants live in types.ts; JSX component has no state, CVA calls, or business logic.
• Public props with runtime defaults have matching @default JSDoc in types.ts (node scripts/verify-prop-default-docs.mjs).
• Uses design tokens from theme.css; no hardcoded colors or arbitrary color utilities in the component implementation. The Storybook-only gray block is intentionally illustrative.
• Storybook covers default, variants, documented states, edge cases, and dark mode when visually different.
• Component audit result is PASS or accepted PASS WITH WARNINGS.
• Visual review result is included when visuals changed.

Accessibility evidence

• Role/name semantics verified with Testing Library queries or equivalent.
• Keyboard-only behavior verified: N/A — CardContainer is intentionally non-interactive.
• Focus lifecycle verified: N/A — component does not manage focus.
• Disabled, required, invalid/error, loading, and empty states expose the expected semantics where applicable: N/A for static visual container.
• Reduced motion behavior is respected where motion changed.
• Screen reader or axe/manual evidence is included below when applicable: N/A for static visual container.

Validation evidence

• TypeScript: pnpm build ✅; commit hook typecheck ✅
• Unit tests: pnpm exec vitest run src/components/atoms/card-container/CardContainer.test.tsx ✅ (22 tests); pnpm test ✅ (560 tests)
• Build/package: pnpm build ✅; pnpm run verify:package ✅
• Storybook or visual check: pnpm storybook-build ✅; Playwright visual review of atoms-cardcontainer--backdrop-blur ✅
• Accessibility check: Testing Library verifies native div semantics, prop passthrough, no default focusability, no interactive ARIA/roles.
• Security/dependency check: N/A — no dependency changes.
• Scripts: shellcheck N/A — no shell scripts modified.

Screenshots or recordings

Visual review was performed locally against the built Storybook BackdropBlur story; transient Playwright artifacts were cleaned before commit.

Notes for reviewer

• backdropBlur uses CSS backdrop-filter, so it blurs what is behind the card. Normal document-flow content cards should keep backdropBlur="none".
• Card backdrop alpha tokens are intentionally separate from navbar alpha tokens to avoid coupling floating card glass to navbar styling.

[Copilot]

Pull request overview

Adds a new CardContainer atom to the design system as a token-backed, non-interactive visual surface, and wires it into the public package exports and design documentation.

Changes:

• Introduces CardContainer (types/hook/component/tests/stories) with variants for surface style, padding, radius, hover lift, and optional glass backdropBlur.
• Extends theme tokens with card backdrop colors, hover glow shadow tokens, and card blur levels.
• Updates docs (DESIGN + COMPONENTS, EN/ES) to document the new frosted/glass card guidance, and exports CardContainer from src/index.ts.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/styles/theme.css	Adds card backdrop, hover glow, and blur tokens used by CardContainer variants.
src/index.ts	Exports CardContainer from the package entrypoint.
src/components/atoms/icon-button/useIconButton.ts	Ref typing adjustment for the button ref (see review comments re: nullability/cast).
src/components/atoms/card-container/useCardContainer.ts	Hook that maps props to native div props + variant className.
src/components/atoms/card-container/types.ts	CVA variants + public prop types/defaults for CardContainer.
src/components/atoms/card-container/index.ts	Barrel export for the atom and its types.
src/components/atoms/card-container/CardContainer.tsx	Stateless component wrapper that applies hook output to a <div>.
src/components/atoms/card-container/CardContainer.test.tsx	Hook + component behavior tests for passthrough props and variants.
src/components/atoms/card-container/CardContainer.stories.tsx	Storybook coverage for defaults, variants, spacing, radius, hover, blur, semantics, nested content.
src/components/atoms/button/useButton.ts	Ref typing adjustment for the button ref (see review comments re: nullability/cast).
docs/DESIGN.md	Documents new card-backdrop-bg and updated frosted/glass guidance (ES).
docs/DESIGN.en.md	Documents new card-backdrop-bg and updated frosted/glass guidance (EN).
docs/COMPONENTS.md	Updates system rules/examples around frosted cards and blur usage (ES).
docs/COMPONENTS.en.md	Updates system rules/examples around frosted cards and blur usage (EN).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.