# OSHUN V1 Card-Avoidance Rules

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.md`
- `docs/releases/v1/specs/layout-density-tiers.md`
- `docs/releases/v1/scope/imagery-illustration-texture-ambient-media-rules.md`
- `docs/releases/v1/design/customer-visual-thesis.md`
- `apps/oshun/web/src/design-system/components/Card.tsx`
- `apps/oshun/web/src/components/home/DomainCardGrid.tsx`
- `apps/oshun/web/src/components/library/LibraryDashboard.tsx`
- `apps/oshun/web/src/components/welcome/WelcomePageView.tsx`
- `apps/oshun/web/src/components/explore/ExploreDashboard.tsx`
- `docs/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.tsx`
- `apps/oshun/web/src/components/home/DomainCardGrid.tsx`
- `apps/oshun/web/src/components/library/LibraryDashboard.tsx`
- `apps/oshun/web/src/components/welcome/WelcomePageView.tsx`
- `apps/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-3` peer 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
