Design System
Relevant source files
The following files were used as context for generating this wiki page:
PRKS implements a dense, calm, and utilitarian research workspace design system. The system prioritizes information density and functional clarity over decorative elements, using a semantic token system and a canonical component vocabulary to maintain consistency across both legacy JavaScript and modern Vue 3 implementations.
The design system architecture bridges classic CSS classes with typed TypeScript components. It ensures a "quiet" selected state, avoiding loud outlines or glows in favor of surface color changes and font weight adjustments.
Sources: DESIGN.md, tests/test_design_system.py:129-130, frontend-app/README.md:1-15
Semantic Token System
The PRKS visual language relies on a centralized system of CSS variables (tokens) that define colors, spacing, typography, and UI behavior. These tokens ensure that changes to the brand mark or application accent propagate throughout the interface consistently.
Core Token Categories
| Category | Prefix | Purpose |
|---|---|---|
| Surfaces | --surface- | Defines background levels, inset states, and selection backgrounds. |
| Text | --text- | Categorizes typography by hierarchy (primary, secondary, tertiary, inverse). |
| Accent | --accent- | Controls the application primary action color (#6d6cf7). |
| Status | --danger-, --success- | Semantic colors for alerts, validation, and sync status. |
| Radii | --radius- | Enforces square corners; most functional radii are set to 0. |
Sources: tests/test_design_system.py:44-93, tests/browser/design_system.html:112-125
Design Token Relationships
The following diagram illustrates how semantic tokens map from base definitions to specific UI state applications.
Component Vocabulary
The "Canonical Component Vocabulary" defines a set of standard classes and Vue components that serve as the building blocks for the PRKS interface. Components are organized into primitives that manage layout, actions, and information display.
Action Primitives
PRKS enforces strict button semantics. Components like PrksButton wrap standard .prks-btn classes to provide consistent states for primary, secondary, and danger actions.
.prks-btn--primary: Used for the main action in a view..prks-btn--secondary: Used for supporting actions..prks-btn--ghost: Used for low-emphasis or toolbar actions..prks-icon-btn: Square chrome buttons for icon-only triggers.
Sources: frontend-app/src/components/PrksButton.vue, frontend-app/README.md:65-90, tests/test_design_system.py:95-127
Summary and Overview Primitives
Dense information strips provide context without overwhelming the workspace. The system uses specific classes for different summary types.
| Class | Usage |
|---|---|
.prks-page-header | Main title row with context links and actions. |
.prks-page-summary | High-level counts (e.g., "12 folders · 148 files"). |
.prks-scope-line | Filters and matching counts (e.g., "12 of 48 matching"). |
.prks-rel-summary | Identity strips for entities (People, Tags, Folders). |
.prks-state-summary | Compact status indicators in the right panel. |
Sources: frontend/js/overview-primitives.js:10-25, tests/browser/design_system.html:255-267
Interaction and Layout Logic
PRKS maintains a strict policy regarding layout behavior, particularly concerning workspace management and selection states.
Workspace Tab Visual Contract
The system distinguishes between "Local / content tabs" and "Workspace tabs." Local tabs reside within a specific pane (e.g., Details vs. Annotations), while Workspace tabs manage the top-level pane organization.
- Selected State: Active tabs and selected list rows must never use "loud" purple outlines or persistent accent stripes. Instead, they use
--surface-selectedand font-weight changes. - Splitter Behavior: The
.prks-splittercomponent manages the resize relationship between Main and Secondary panes.
Sources: tests/test_design_system.py:171-190, tests/browser/design_system.html:364-410
Sync and Status Indicators
Visibility of background operations is handled through the status family. Sync dots use semantic tokens (--success, --danger, --warning) to communicate state without hardcoded hex values.
Implementation Policies
Inline-Style Policy
PRKS strictly prohibits inline style attributes in templates unless they are used to pass dynamic CSS variables (prefixed with --). All visual property ownership belongs to the stylesheet.
Accessibility Standards
Accessibility is a core requirement of the design system.
- Every visible input must have an associated
<label>or anaria-label. - Icons are treated as decorative (
aria-hidden="true") when accompanied by text. - Contrast ratios are maintained through the semantic token palette.
Sources: tests/test_design_system.py:148-163, tests/test_design_system.py:349-366, frontend-app/README.md:110-120
Conclusion
The PRKS Design System provides a robust framework for a specialized research environment. By enforcing a "dense and calm" aesthetic through semantic tokens and standardized primitives, the system ensures that the software remains utilitarian and accessible across its various functional surfaces. Significant components are documented in DESIGN.md, and structural guards in test_design_system.py ensure ongoing adherence to these principles during development.