Instruction file imported from mGhassen/Forja (.cursor/rules/forja-design-system.mdc). Copyright stays with the author.

Forja design system (RFC-025 · RFC-095)

Source of truth: apps/forja/lib/shared/foundation/primitives/ — import via package:forja/shared/foundation/primitives/primitives.dart.

Design alone / data alone (RFC-095)

Foundation is a shadcn-style design system. Composers under foundation/components/ take props + callbacks only. Features own controllers/stores and map domain data into those props.

Example: KitPortalsChip / KitSidePanelOverlay / KitPortalListPanel ← IPTV (IptvPortalsTopBarButton, IptvPortalsChromeHooks) wires portal label, health, seats, list.

Golden reference: KitSourcesPanel — features wire load/play via callbacks.

Visual language

• Flat cinematic shell — no BackdropFilter, frosted glass, or ambient glows on shell nav, home chrome, or player control bars.
• Exception — sliding side panels: media-details Sources uses ForjaFrostedPanel with BackdropFilter. Player overlays (Episodes, torrent files) pass a video screenshot as frozenFrame and blur that with ImageFiltered — do not put BackdropFilter over live video (freezes macOS). Do not scatter ad-hoc blur elsewhere.
• Hero overlays use ForjaShellColors.cinematic (fixed light-on-imagery), not AppTheme.primaryColor.
• Spacing and breakpoints come from ShellTokens / DetailsTokens — do not hardcode magic numbers that already exist there.

Tokens

ShellTokens — shell chrome, Home, catalog

DetailsTokens — media details

Details gutters deliberately alias ShellTokens.homeSectionHorizontalPadding / bodyMaxWidthDesktop so details stay aligned with catalog rows.

When adding a reused constant: shell/catalog → ShellTokens, details surfaces → DetailsTokens. One-off padding inside a single widget is fine.

Colors (ForjaShellColors)

• Shell chrome: textPrimary, textSecondary, iconMuted, borderSubtle, surfaceElevated
• Selection / resume: chipSelectedBg, chipSelectedBorder, progressFill
• Menus / dropdowns: ForjaShellColors.cinematic.menuSurface
• Floating player menus: PlayerPopupTokens in shared/player/controls/menus/player_popup_panel.dart (translucent dark shell ~α0.82 like player side panels; select cards use idle cardBg, selected/hover/focus accentFill + green border — never solid accent fill)
• Do not use raw Colors.white54 for new shell UI when a semantic token exists.

Buttons

Toggles

Prefer ForjaSwitch(scale: ForjaSwitch.settingsScale) in dense settings lists. Do not style raw Switch( with ad-hoc activeTrackColor / thumbColor.

Section titles

• Horizontal catalog rows: ShellSectionTitle or ShellSectionTitle.titleStyle
• Media details sections (Cast, Trailers): same titleStyle — plain text, no underline, no icon prefix

Focus / TV

• Interactive list tiles and cards: wrap with FocusableControl from app_theme.dart (keyboard + focus ring).
• Platform layout and input: read ShellScope.metrics / ShellScope.inputPolicy — not ShellTokens.isTvLayout in widgets.
• Platform shell switches live only in shell/adapters/ (ShellHost, DesktopShell, TvShell, MobileShell).

Text inputs (TV) — focus only until OK

D-pad land = focus/highlight only. Never activate. Opening the keyboard, edit mode, or search chrome requires explicit OK / Select / Enter / tap — never onFocusChange(true) or autofocus-into-edit.

Forbidden on TV: raw TextField that becomes editable / opens IME when focused; wiring focus listeners to openSearch / beginEditing. Full rule: forja-tv-scope.mdc → TV text inputs.

Forbidden without explicit approval

• Ad-hoc BackdropFilter / ImageFilter.blur outside ForjaFrostedPanel (and existing IPTV frosted panels)
• Ad-hoc pill/chip styles that duplicate TorrentSourceToggle / chip selected tokens
• Ad-hoc Switch( / SwitchListTile color overrides — use ForjaSwitch / theme tokens
• Duplicating hero title or meta rendering — use shared/foundation/components/hero/ (see forja-shared-ui.mdc)