Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-059
Related:
docs/releases/v1/scope/minimal-chrome-rules.mddocs/releases/v1/specs/layout-density-tiers.mddocs/releases/v1/scope/imagery-illustration-texture-ambient-media-rules.mddocs/releases/v1/design/customer-visual-thesis.mdapps/oshun/web/src/design-system/components/Card.tsxapps/oshun/web/src/components/home/DomainCardGrid.tsxapps/oshun/web/src/components/library/LibraryDashboard.tsxapps/oshun/web/src/components/welcome/WelcomePageView.tsxapps/oshun/web/src/components/explore/ExploreDashboard.tsxdocs/releases/v1/specs/todos.md
1. Purpose#
This document defines the canonical card-avoidance rules for OSHUN V1 and explicitly states when card treatment is allowed versus prohibited.
The product already contains both a shared card primitive and many card-heavy surfaces:
apps/oshun/web/src/design-system/components/Card.tsxapps/oshun/web/src/components/home/DomainCardGrid.tsxapps/oshun/web/src/components/library/LibraryDashboard.tsxapps/oshun/web/src/components/welcome/WelcomePageView.tsxapps/oshun/web/src/components/explore/ExploreDashboard.tsx
Those implementations are useful evidence, but they also demonstrate the exact drift this rule set is meant to stop: generic SaaS composition built from bordered tiles, hover lifts, and repeated wrappers instead of deliberate sections, rows, rails, and reading lanes.
2. Core Doctrine#
2.1 No Cards By Default#
Card treatment is not the default layout language for OSHUN V1.
The default language is:
- open sections
- rows
- rails
- split panes
- lists
- tables
- dividers
- media planes
2.2 A Card Must Be The Interaction#
A card is allowed only when the whole object is meant to be understood and acted on as one bounded unit.
If removing the border, radius, shadow, and background fill would not weaken meaning, focus, or interaction clarity, the surface probably should not be a card.
2.3 Cards Must Reduce Complexity, Not Multiply It#
A valid card groups one object into one clear target.
Invalid card usage adds extra frames around content that was already legible as plain layout.
2.4 Card Count Is A Design Smell#
When a screen starts to rely on many peer cards to create hierarchy, the actual hierarchy is probably weak.
3. Canonical Alternatives To Cards#
Before using a card, try one of these first:
| Need | Default alternative |
|---|---|
| separate two content groups | spacing plus divider |
| present a sequence of objects | list rows or stacked sections |
| preserve reading continuity | split pane or side rail |
| show metadata next to content | inline cluster or secondary rail |
| create a strong landing impression | media plane plus constrained text column |
| frame a workspace | one shared canvas with local panels, not many nested tiles |
4. Allowed Card Cases#
Card treatment is allowed only in the following canonical cases.
4.1 Selectable Object Tiles#
Allowed when:
- a discrete object must be chosen from a mixed grid or carousel
- the whole tile is the tap/click target
- each tile has bounded metadata and one primary action
Examples:
- domain selection in onboarding
- collection or content pickers where each item is self-contained
- saved-object browse modules when row format would materially weaken scanning
4.2 Media-Backed Preview Objects#
Allowed when:
- the object includes a cover, image crop, poster, or visual preview
- the crop itself is part of the decision
- the object benefits from a bounded hover or focus target
Examples:
- curated content preview with cover image
- collection tile with meaningful artwork
- media-library asset preview
4.3 Bounded Utility Modules#
Allowed when:
- the object is a small, self-contained utility block
- the user expects it to be manipulated as one object
- the block is not repeated so many times that it becomes page grammar
Examples:
- one floating picker
- one transient support module
- one summary object in a mixed canvas
4.4 Specialist Secondary Evidence Objects#
Allowed only in secondary contexts when:
- the evidence item is treated as an individual inspectable record
- the primary reading lane remains uncarded
- cards do not multiply into the main page grammar
Examples:
- secondary citation list items
- compare candidates in a supporting side panel
5. Prohibited Card Cases#
5.1 Hero Cards#
Prohibited:
- hero cards
- boxed hero content pretending to be premium landing design
- first-view metric or feature card mosaics as the main landing expression
Hero and landing surfaces must use composition and media, not a wall of boxes.
5.2 Page-Wide Card Stacking#
Prohibited:
- wrapping every section in its own bordered tile
- stacking card after card to simulate page structure
- turning a whole route into repeated rounded rectangles
5.3 Primary Reading Content In Cards#
Prohibited for:
- article body text
- study passages
- notebooks
- commentary reading lanes
- instructional ritual copy
Primary reading surfaces should feel editorial or spatial, not boxed.
5.4 Nested Cards#
Prohibited:
- cards inside cards as the default
- card grids inside larger parent cards
- mini cards added only to create more visible hierarchy
One bounded object layer is the maximum default.
5.5 Operator Dashboard Card Mosaics#
Prohibited:
- admin dashboard card walls
- queue and incident surfaces composed from many peer KPI boxes instead of tables, grouped summaries, or inspectors
- repeated "signal cards" where rows or panels would scan faster
Operator work should feel like an instrument panel, not a homepage widget deck.
5.6 Decorative Cards#
Prohibited when the card exists only for:
- gradient styling
- hover lift
- shadow decoration
- fake premium signaling
- turning ordinary text blocks into "components"
6. Surface Mapping#
| Surface family | Default card posture |
|---|---|
| welcome and marketing-like landing work | cards prohibited in the hero; limited support tiles only below the fold |
| customer home and continuity surfaces | prefer rails, rows, and mixed open sections; allow a few object cards only where the object itself is the action |
| explore and discovery | cards allowed for discrete media/object picks, but avoid turning the entire route into peer-tile sameness |
| library and saved material | prefer open shelves, grouped rows, and reading-oriented structure; cards are a secondary option, not the page grammar |
| Veritas and Nisaba reading flows | primary content uncarded; secondary evidence or compare objects may be carded sparingly |
| admin/operator surfaces | shared work canvas, panels, tables, queues, and inspectors instead of dashboard-card sprawl |
7. Density And Hierarchy Rules#
7.1 Card Count Caps#
As a heuristic:
- first viewport should rarely contain more than
2-3peer cards on customer surfaces - a full route should not depend on cards for every major section
- if a surface needs many peer objects, shift to rows, grouped lists, or a governed grid with much lighter framing
7.2 Hierarchy Inside Allowed Cards#
When cards are allowed:
- keep one headline
- keep metadata compressed
- keep one dominant action
- avoid adding pills, badges, dividers, and mini-panels until the card becomes its own dashboard
7.3 Visual Weight#
Allowed cards should use the lightest framing that still preserves objectness:
- subtle border before strong shadow
- quiet background before glass effect
- one accent cue before multicolor styling
8. Shared Primitive Guidance#
The shared Card primitive in
apps/oshun/web/src/design-system/components/Card.tsx remains valid as an
opt-in bounded-object primitive.
It must not be treated as the default wrapper for:
- page sections
- reading groups
- workspace panels
- whole-route composition
Its presence in the design system is not permission to use cards everywhere.
9. Anti-Patterns Seen In Current Repo Signals#
These current patterns should be treated as redesign debt unless a stronger case is documented:
- welcome surfaces where cards substitute for stronger hero composition
- domain card grids that use card styling plus hover decoration as the main hierarchy engine
- library and explore sections where many similarly framed objects flatten scan priority
- glass-card stacking used as a shorthand for premium UI
10. Acceptance Standard#
A redesign satisfies V1-UX-059 only when all are true:
- it can explain why each remaining card is a bounded interactive object
- primary reading, hero, and workspace structures are not card-dependent
- prohibited card cases are absent
- allowed cards use the lightest sufficient framing
- removing unnecessary cards would not reveal a weak or missing hierarchy, because the hierarchy is already explicit