polaris-task-force/DESIGN.md

Polaris Task Force Design System

1. Atmosphere & Identity

Polaris is a dark operations console: focused, quiet, and information-dense without feeling cramped. The signature is a neutral charcoal surface hierarchy with restrained white controls and small, purposeful state accents.

2. Color

Palette

Role	Token	Usage
Surface / page	bg-background	Frontend page background
Surface / card	bg-card	Elevated content sections
Text / primary	text-foreground	Headings and primary labels
Text / secondary	text-muted-foreground	Descriptions and supporting copy
Interactive / primary	bg-primary, text-primary-foreground	Primary actions and checked controls
Interactive / focus	ring-ring	Keyboard focus indicators
Border	border-border	Card and control boundaries
Status / error	text-destructive	Inline validation and failure copy
Status / success	text-emerald-500	Existing save confirmations

Rules

• Use semantic Tailwind tokens backed by src/app/(frontend)/styles.css; do not add raw colors in frontend components.
• Preserve the dark neutral palette and use accent color only for interactive state.

3. Typography

Scale

Level	Token	Usage
Page title	text-lg font-semibold	Route heading
Card title	font-semibold	Section heading
Body	inherited text-base	Primary content
Supporting	text-sm text-muted-foreground	Descriptions and helper text
Compact	text-xs	Secondary metadata only

Font Stack

• Primary: Geist, sans-serif
• Mono: Geist Mono, monospace

4. Spacing & Layout

Base Unit

Spacing follows Tailwind's 4px scale. Existing frontend stacks use gap-1, gap-2, gap-3, gap-4, and gap-6.

Rules

• Use flex flex-col gap-* for vertical stacks; do not use space-y-*.
• Account content is constrained with max-w-2xl and uses gap-6 between cards.
• Preference sections use CardHeader and CardContent; controls use gap-4.
• Preference sub-options are indented with pl-6 and remain one readable column on narrow screens.

5. Components

Card sections

• Structure: Card → CardHeader → CardTitle + CardDescription; CardContent body.
• Variants: default dark card surface.
• Spacing: built-in card padding; internal control stack uses gap-4.
• States: default, focus/error states belong to child controls.
• Accessibility: headings and descriptions provide section context.
• Motion: no section-level motion.
• Layout: vertical stack.

Poker table surface

• Purpose: The poker table is a diegetic game surface. The velvet felt carries the board, the dealer station, opponent arc, and the player's action console without floating control overlays.
• Material: Preserve the existing velvet felt gradient, dark inset rim, and restrained gold trim. The action console is a darker inset panel with the same trim language, while chips use dark, clay, and gold-trim variants for action hierarchy.
• Primitives: poker-felt-table, poker-dealer-station, poker-seat-arc-*, poker-action-console, poker-hand-placard, and poker-chip.
• States: betting and waiting console states, acting-seat highlight, folded and eliminated players, showdown result, game-complete placement, open and occupied waiting seats, and reduced-motion deal presentation.
• Accessibility: The cosmetic dealer station is labelled as a station and is not included in player or seat data. Action controls remain native buttons and inputs with visible focus states. Card labels continue to describe face-up and face-down cards.
• Motion: Cards originate visually at the dealer shoe using transform and opacity with a 60ms stagger. Reduced motion removes the deal animation while retaining static card tilts and highlight states.
• Layout: The felt is a flat-bottom semicircle. Opponents occupy count-aware upper arc slots, the dealer is top-center, community cards sit in the middle, and the user's console is pinned to the flat bottom edge. Fullscreen increases felt depth without moving the console out of the viewport canvas.

Locker inventory surface

• Purpose: The authenticated locker is a Polaris operations surface: a dense, readable inventory rather than a literal game replica. The grid is the focal region and selection context is kept adjacent to it.
• Palette: Use the existing semantic neutral tokens: bg-background for the page, bg-card/bg-muted for framed regions, border-border for structure, text-foreground and text-muted-foreground for hierarchy, and bg-primary/ring-ring for active selection and primary actions. Amber utility accents are reserved for existing equipment/skin meaning; they do not become a second surface palette.
• Typography: Keep Geist for interface copy and Geist Mono with tabular-nums for coordinates, counts, dimensions, and other inventory metadata. Compact labels use the existing text-xs level, never ad-hoc display sizes.
• Primitives:
  • locker-shell: one responsive page region with a compact control band and a single-column fallback below xl.
  • inventory-frame: a strong rectangular border around the existing two-dimensional grid. The grid may scroll only inside this bounded region when its footprint exceeds the available inline size; the page itself must not gain a horizontal scrollbar.
  • selection-rail: selected-item context and actions sit beside the inventory at xl and later, then become an inline section below the grid at narrower widths. It remains readable when no item is selected.
  • metadata-strip: a compact cluster for occupancy, dimensions, and drag/drop guidance, using 4px spacing and semantic muted text.
  • wardrobe-slot-board: a body-ordered rectangular board: head/face spans the top, torso and pack occupy the middle, and weapons/attachments plus sidearm finish the lower row. The primary weapon owns an indented attachment subgroup for optic, muzzle, and bipod slots. Each slot is a labeled semantic button with distinct filled and empty states; the board is driven by WARDROBE_SLOT_LAYOUT and never relies on a character image as its control surface.
• States: default, hover, focus-visible, selected, search-highlight, valid drop, invalid drop, attachment drop, empty, error, disabled, and reduced-motion. Selected items use a visible semantic ring; placement feedback stays inside the grid cells; empty and error states retain the existing user/manager-specific copy.
• Accessibility: Tabs remain native shadcn tab semantics. Every icon-only button has an accessible label, every meaningful thumbnail keeps descriptive alt text, draggable items retain dnd-kit keyboard attributes, and all actions keep visible focus-visible rings. The responsive rail must not reorder focus away from the selected item context.
• Motion: Preserve the existing dnd-kit activation threshold and absolute-position/ResizeObserver mechanics. Interaction polish is limited to existing shadcn color transitions, transform/opacity drag feedback, and the existing search highlight; prefers-reduced-motion disables highlight animation and nonessential transitions. No decorative looping motion is introduced.
  • Responsive behavior: At 375px the shell becomes one readable column with no viewport-level horizontal overflow. Only the inventory-frame may expose bounded two-dimensional scrolling when required by the configured grid; the selection rail follows the grid inline, while the tab/search control cluster wraps before it can overflow. The inventory and selection rail use the side-by-side layout only at xl and above so the grid remains dominant and rail labels remain readable. The wardrobe slot board keeps its body order at lg and collapses regions to one readable column below that threshold.

Mission card

• Structure: linked Item with ItemHeader, ItemMedia, ItemTitle, ItemContent, and ItemDescription primitives.
• Variants: default uses the neutral outline surface; image adds an optional cover image with a translucent gradient overlay. The contextual default is image when a cover image URL is available.
• Metadata: compact cards show operation/status, date/time, map, player slots, and campaign; full cards additionally show estimated duration.
• States: default, image, hover, focus-visible, and reduced-content/full-detail display.
• Accessibility: the entire card is one keyboard-reachable link; decorative cover images use empty alt text and are hidden from assistive technology.
• Motion: existing 200ms scale, border, and foreground transitions communicate the linked-card affordance; no decorative animation.
• Layout: responsive metadata wraps on narrow screens while the image layer stays absolutely positioned behind content.

Preference row

• Structure: label.flex.items-center.justify-between with text on the left and a shadcn control on the right.
• Variants: primary setting and indented notification setting.
• Spacing: gap-3 for label copy; pl-6 for dependent settings.
• States: default, checked, unchecked, disabled, focus-visible.
• Accessibility: the label owns the control relationship; disabled dependent rows use both disabled controls and reduced-opacity presentation.
• Motion: shadcn control transition only.
• Layout: responsive cluster with a single-column text block.

Switch

• Structure: shadcn Switch with an associated label and optional description.
• Variants: primary and dependent/disabled.
• Spacing: control row uses gap-4.
• States: unchecked, checked, hover, active, focus-visible, disabled.
• Accessibility: keyboard reachable with visible focus and native switch semantics.
• Motion: 100–150ms control transition.
• Layout: inline control at the row edge.

RadioGroup

• Structure: shadcn RadioGroup with RadioGroupItem and Label pairs.
• Variants: two-option roster label selection.
• Spacing: option cluster uses gap-4.
• States: selected, unselected, hover, active, focus-visible.
• Accessibility: grouped options retain native radio semantics and labels.
• Motion: control transition only.
• Layout: wraps on narrow screens without horizontal overflow.

Transfer workflow surface

• Structure: the account AssignmentCard owns current-assignment context and opens the RequestTransferDialog; /transfers uses a stack of Card sections containing request, approval, and escalated-resolution cards.
• Variants: request cards, leader approval cards, and superuser resolution cards share the neutral card surface; status meaning is carried by the existing Badge variants.
• States: loading, empty, pending, approved, rejected, appealed, escalated, completed, cancelled, denied, error, and success feedback.
• Accessibility: every dialog has a visible title and description, every textarea has a label, rejection requires a non-empty reason, and destructive actions remain keyboard reachable with the existing focus ring.
• Motion: use the existing shadcn dialog, button, and toast transitions only; no decorative section animation. Async buttons expose their pending state and disable competing actions.
• Layout: the transfer list is a single document scroll region inside the authenticated shell; cards use an intrinsic one-column-to-two-column grid and remain readable at narrow widths.

Helpdesk ticket controls

• Structure: ticket list and detail surfaces use the existing Item, Badge, Button, and Dialog primitives. The author-only edit dialog contains labeled title, category, priority, and description controls; vote state uses one Button with a visible count.
• States: edit controls expose default, pending, success, and error states. Vote controls expose unvoted, voted (aria-pressed), pending, and disabled states; canceled tickets disable voting.
• Accessibility: edit dialogs have a title and description, every field has an associated label, and vote buttons announce both the action and count without relying on iconography.
• Motion: use existing shadcn dialog and button transitions only.
• Layout: controls wrap on narrow screens and never turn a card-wide navigation link into a nested interactive target.

6. Motion & Interaction

Timing

Type	Duration	Usage
Micro	100–150ms	Switch and radio state feedback
Standard	200–300ms	Button hover and focus transitions

Rules

• Keep motion in existing shadcn controls and buttons; do not add decorative animation to the account form.
• Preserve visible keyboard focus and prefers-reduced-motion behavior from the component primitives.

7. Depth & Surface

The frontend uses a mixed strategy: card borders plus the existing shadcn card shadow, with tonal changes for muted controls. New preference sections should compose the existing Card primitive rather than introduce custom shadows or radii.

8. Accessibility Constraints & Accepted Debt

Constraints

• Target WCAG 2.2 AA.
• Every interactive control must be keyboard reachable with a visible focus state.
• Dependent notification controls must expose their disabled state through the actual control, not only visual opacity.
• The form must reflow to one readable column at mobile widths without horizontal scrolling.

Accepted Debt

Item	Location	Why accepted	Owner / Exit
Existing success color uses text-emerald-500	Account forms	Preserve established feedback styling in this focused redesign	Consolidate account feedback tokens in a future account UI pass