DESIGNER.md

contractVersion	1
project	type uiRisk defaultBehavior unknown production existing-systems-first
authority	priority conflictPolicy user-explicit-request existing-project-systems designer-contract inferred-local-patterns generic-defaults existing-system-wins-unless-user-requests-migration
i18n	status authority policy ifMissing existing library paths defaultLocale supportedLocales keyStyle custom packages/ui/src/i18n packages/app/src/context/language.tsx packages/console/app/src/context/language.tsx en en tr custom hardcodedUserText missingKeyBehavior textExpansion rtl warn ask 30% support-if-project-supports-rtl greenfield existingProject ask do-not-install-without-user-approval
theme	status authority modes policy existing type paths tailwind-css-vars packages/ui/src/theme packages/ui/src/styles packages/ui/script/tailwind.ts rawColors rawSpacing semanticTokensRequired addMissingTokensToTheme warn discourage false true
components	authority policy paths storybook importAlias packages/ui/src/components packages/ui-team/src false @opencode-ai/ui existingFirst duplicateComponents localOneOffAllowed missingVariantBehavior reusableComponentLocation requireStoryForReusable true warn only-if-truly-local extend-existing-component packages/ui/src/components false
motion	status authority policy existing library paths motion packages/ui/src/components/motion-spring.tsx packages/app/src/index.css packages/ui-team/src/team-components/memory-system.css packages/ui-team/src/team-tool/team-tools.css useExistingUtilities reducedMotion infiniteAnimation preferredProperties forbidden true required loading-status-only opacity transform
accessibility	contrast focusVisible keyboardNavigation ariaForInteractiveControls WCAG-AA required required recommended
verification	required visual packages/ui: bun run typecheck packages/ui-team: bun run typecheck packages/app: bun run typecheck requiredWhenLayoutChanges true
agent	rules Read this Designer contract before UI, UX, styling, theme, i18n, component, motion, accessibility, desktop-shell, or docs-site work. Prefer existing package authorities before creating local one-off design systems. Do not add locales, theme tokens, component libraries, or blocking Designer enforcement without source evidence and user approval.
designer	enforcement mode errorRules warningRules report duplicateComponents hardcodedUserText rawColors

OpenCode Designer Contract

Purpose

This root file is the legacy Designer contract fallback for OpenCode. It documents the project-local frontend and design authorities that Ayaz, frontend, reviewer, QA, and Designer-governed workflows should inspect before user-visible changes while no namespace contract exists.

The Designer runtime prefers .opencode/memory/designer/DESIGNER.md, then .opencode/memory/designer/frontend-design.yaml, then .opencode/memory/designer/frontend-design.yml, and uses this root DESIGNER.md only as a legacy fallback/migration source. If a namespace contract is intentionally introduced, it shadows this root file; do not treat root frontend-design.yaml, root frontend-design.yml, or DESIGN.md as canonical Designer contract paths.

Product and surface scope

OpenCode is an open-source AI coding agent / AI-powered development tool. Its user-facing surfaces include:

• terminal/TUI client surfaces referenced by root product docs,
• shared app shell in packages/app,
• browser console/site in packages/console/app,
• desktop shells in packages/desktop and packages/desktop-electron,
• reusable UI primitives in packages/ui,
• team/designer-facing panels in packages/ui-team,
• documentation site surfaces in packages/docs.

Desktop identity is mixed in the repo (packages/desktop uses Tauri while packages/desktop-electron is Electron). Treat both as active shell surfaces unless a task provides a narrower target.

Authorities to inspect first

• Shared components and styling: packages/ui/src/components, packages/ui/src/styles, packages/ui/src/theme.
• Theme contract and token generation: packages/ui/src/theme/types.ts, packages/ui/src/theme/context.tsx, packages/ui/src/theme/desktop-theme.schema.json, packages/ui/script/tailwind.ts.
• i18n: live shared locale files are packages/ui/src/i18n/en.ts and packages/ui/src/i18n/tr.ts; app shell language context lives in packages/app/src/context/language.tsx; console language context lives in packages/console/app/src/context/language.tsx.
• Component examples: no dedicated component-example package is maintained; inspect component source and consuming surfaces directly.
• Motion and reduced-motion evidence: packages/ui/src/components/motion-spring.tsx, packages/app/src/index.css, and reduced-motion CSS in packages/ui-team.

Operating guidance

• Use existing package authorities first. Extend shared primitives under packages/ui for reusable UI; keep truly local one-offs near the owning surface.
• The i18n contract uses library: custom because the Designer schema enum does not include @solid-primitives/i18n; the actual app dependency is @solid-primitives/i18n.
• Do not claim additional live locales without checking packages/ui/src/i18n/ and language contexts. Current verified shared locales are en and tr.
• Keep Designer enforcement in report mode until the user explicitly asks for blocking/warn enforcement and verification has been updated.
• Prefer package-local preview or consuming-surface inspection for reusable components; do not require dedicated examples for every small/local component until the project adopts that rule.

Verification guidance

For UI/design work, choose the smallest package-local check that proves the changed surface:

• packages/ui: bun run typecheck; use package-local preview or consuming surfaces for visual inspection when component behavior changes.
• packages/app: bun run typecheck; use app-specific build or preview checks when the changed path requires runtime UI evidence.
• packages/ui-team: bun run typecheck when team/designer panels change; use package-local build or preview checks for runtime UI evidence.
• packages/opencode: bun run typecheck when the Designer runtime, schema, contract lookup, lint, or summary behavior changes.

Repository test suites have been removed; root bun run test remains blocked. Prefer package-local typecheck, build, lint, or runtime inspection that proves the changed surface.

Update triggers

Update or migrate this contract when any of these change:

• Designer runtime lookup, schema, adapters, lint/check/summary behavior, or enforcement policy.
• UI package ownership, component library exports, package names, or route/shell ownership.
• Theme/tokens/styles paths or Tailwind variable generation.
• i18n library, language context, locale files, default locale, or supported locale set.
• Motion utilities, reduced-motion handling, accessibility requirements, or verification commands.
• Adoption of namespace .opencode/memory/designer/DESIGNER.md, .opencode/memory/designer/frontend-design.yaml, or migration away from this root legacy fallback.

Known gaps

• No separate frontend-design.yaml is created; Markdown frontmatter is the active contract shape.
• Accessibility expectations are based on detected authorities and conservative defaults; no standalone project accessibility policy was found.
• Desktop design ownership remains split between Tauri and Electron packages in repo evidence.