Brainforge Knowledge

brainforge-brand-kit-allowed-surface-2026-04-16

2 min read

Allowed surface — brainforge-brand-kit (agent contract)

Date: 2026-04-16
Scope: UI built inside the Astro component-library using this kit. For The Forge (Next.js), see forge-vs-brand-kit-strategy-2026-04-16.md and platform ESLint (arbitrary Tailwind guardrails).

In-bounds

Semantic CSS variables (prefer these in custom CSS)

Use names from themes/brainforge.css / design-tokens.md, for example:

  • Surfaces: --bg-root, --bg-canvas, --bg-card, --bg-hero
  • Text: --fg-primary, --fg-secondary, --fg-tertiary, --fg-on-dark
  • Accent: --accent, --accent-dark, --accent-brand
  • Borders/shadows: --border, --border-strong, --shadow-card
  • Shape: --radius-card, --radius-button
  • Fonts: --font-primary, --font-secondary, --font-display
  • Motion: --duration-fast, --duration-normal, --ease-out
  • Chart: --chart-green, --chart-blue, … (full set in theme file)

Token-backed utilities (from tokens.css + global.css)

Examples: bg-token-surface-hero, text-token-gradient-brand, gradient utilities prefixed bg-token-*, semantic bg-bg-root, text-fg-primary, border-border, type scale classes per design-tokens.md (type-h1, …).

Tailwind layout / spacing (scale-based)

Use Tailwind scale utilities (flex, grid, gap-4, p-6, max-w-*, responsive prefixes) without arbitrary bracket values unless approved.

Astro components (prefer over raw markup)

For standard patterns, import from src/components/:

  • Forms: Input, Textarea, Select, Checkbox, RadioGroup, Switch, DateInput, TagInput, MultiSelect
  • Structure: Navbar, Sidebar, HeroSection, SectionHeader, FeatureCard, DataTable
  • Feedback: Notification, ProgressBar, Loader, Popover, Tabs
  • Charts: BarChart, LineChart, ChartContainer, … (see src/pages/charts.astro for inventory)

Extend via the documented class prop where components expose it (e.g. Input.astro).

Themes

Default: data-theme="brainforge" on <html>. Only use Labs tokens/classes when the page is explicitly scoped to data-theme="labs".

Out-of-bounds (without explicit human approval)

  • New hex/rgb not mapped through theme or tokens.css.
  • Arbitrary Tailwind values: p-[13px], text-[#333], w-[37rem] except rare layout math with a comment and ticket reference.
  • Parallel button/card/input markup when an Astro primitive already exists.
  • Inline layout styles (style="marginTop: …") for things Tailwind + theme already express.
  • Copy-paste from unrelated design systems (shadcn defaults, random Dribbble) that ignore Brainforge semantic colors.

“Parallel systems” check

Before merging, ask: Did this PR introduce a new visual dialect (colors, radii, button shapes) that is not one of the theme variants? If yes, realign to tokens or get design sign-off.

Graph View

Backlinks