gt-agent-company/openspec/changes/update-agent-index-layout-and-theme-tokens/design.md

Context

The project already contains a theme file at src/static/styles/theme.scss, but the actual app styling is inconsistent:

• theme.scss defines --brand-*, text, background, border, and utility classes
• src/uni.scss and uno.config.ts still reference --theme-* variables The requested change is a cross-cutting design-system alignment focused on the project-wide theme contract.

Goals / Non-Goals

• Goals:

  • Define a single source of truth for the core project palette
  • Use exactly three core brand colors for layout-level styling:
    • Primary: #2F7D32
    • Secondary: #1F2937
    • Tertiary: #F4FBF5
  • Ensure shared consumers such as UnoCSS utilities and uView theme variables resolve from the same theme source

• Non-Goals:

  • Full repo-wide page cleanup in one implementation pass
  • Redefining semantic success, warning, and error states for every page
  • Removing light/dark theme support

Decisions

• Decision: src/static/styles/theme.scss will remain the only file that contains literal core brand values.

  • Why: this file already acts as the closest thing to a design-token source, and centralizing values here avoids duplicating palette values across styling systems.

• Decision: src/uni.scss and uno.config.ts will consume compatibility aliases exported from the same theme source rather than define their own brand colors.

  • Why: the current --theme-* and --brand-* split is inconsistent and invites drift. Compatibility aliases let existing consumers keep working while the project converges on one source.

• Decision: layout-level accents in touched agent-facing pages and shared components will be limited to the approved primary, secondary, tertiary, and neutral tokens.

  • Why: the project had mixed blue, green, orange, red, purple, and cyan across normal layout decoration, which weakens hierarchy and visual cohesion.

• Decision: semantic success, warning, and error colors may remain for exceptional states only.

  • Why: status badges, destructive actions, and warnings still need semantic distinction, but these colors should not become the default decorative palette for dashboards and cards.

Risks / Trade-offs

• Risk: changing the core palette may alter the look of existing shared utilities.
  • Mitigation: keep the implementation scoped to shared tokens plus touched pages, and validate affected agent pages after the token update.

Migration Plan

1. Define the approved brand palette and compatibility aliases in src/static/styles/theme.scss
2. Update src/uni.scss and uno.config.ts to reference the shared aliases
3. Verify touched shared utilities and agent pages for palette consistency

Open Questions

• Which additional agent-facing pages should be migrated to the shared token set in the next cleanup pass