Instruction file imported from Rynaro/alchemists-orchid-papyrus (.github/instructions/alchemists-orchid.instructions.md). Copyright stays with the author.

Alchemist's Orchid - GitHub Copilot Instructions

Color System Context

You are working with the Alchemist's Orchid design token system. This pastel palette features purples, pinks, and cool complements optimized for accessibility.

Critical Rules

NEVER hardcode color values

// ❌ WRONG
const color = '#CDB4DB';
background: '#F8F5F2';

// ✅ CORRECT
const color = tokens.color.primary;
background: var(--ao-color-surface);

NEVER use primitive tokens directly

// ❌ WRONG - primitive token
import { orchid500 } from './tokens/primitives';

// ✅ CORRECT - semantic token
import { colorPrimary } from './tokens/semantic';

ALWAYS verify color accessibility

When pairing colors, use pre-validated combinations:

• Text on surface: color.text.primary on color.surface
• Primary actions: color.on-primary on color.primary
• Links: color.primary.deep on color.surface

Token Quick Reference

Code Patterns

React/TypeScript Components

import { tokens } from '@alchemists-orchid/tokens';

export const Card: React.FC = ({ children }) => (
  <div style={{
    backgroundColor: tokens.color.surface.raised,
    color: tokens.color.text.primary,
    borderRadius: tokens.radius.medium,
  }}>
    {children}
  </div>
);

CSS Custom Properties

.ao-card {
  background-color: var(--ao-color-surface-raised);
  color: var(--ao-color-text-primary);
  border: 1px solid var(--ao-color-secondary);
}

.ao-card:hover {
  box-shadow: 0 4px 12px rgb(var(--ao-color-primary-rgb) / 0.15);
}

Tailwind Classes

<div class="bg-ao-surface text-ao-text-primary border border-ao-secondary">
  <button class="bg-ao-primary text-ao-on-primary hover:bg-ao-primary-deep">
    Action
  </button>
</div>

Accessibility Requirements

• Minimum contrast ratio for normal text: 4.5:1
• Minimum contrast ratio for large text: 3:1
• All interactive elements must have visible focus states
• Use color.primary.deep for focus rings

File-Specific Notes

*.css, *.scss

• Use var(--ao-*) custom property syntax
• Import base variables: @import '@alchemists-orchid/tokens/css';

*.tsx, *.jsx

• Import from @alchemists-orchid/tokens
• Use semantic token names, not primitive values

*.vue, *.svelte

• Bind to CSS custom properties for reactive theming
• Support both light and dark mode via data-theme attribute