PixelPilot uiux-contributing.instructions.md

Contributing to OpenCode UI/UX 2026 Design System

This guide outlines the process for adding new patterns, components, or rules to the OpenCode UI/UX 2026 Design System. Following these steps ensures consistency, maintainability, and adherence to our established standards.

1. Identify the Right Category

Before creating a new file, determine the most appropriate category for your pattern. The .opencode/rules/ directory contains various categories, such as uiux-components.md, uiux-forms.md, uiux-motion.md, etc. If your pattern doesn't fit an existing category, consider if a new category is truly warranted or if it can be integrated into a broader existing rule.

2. File Naming Conventions

All new rule files should follow the uiux-<category-name>.md or <meta-skill-name>.md convention. For example, a new rule for advanced tables would be uiux-advanced-tables.md. Ensure names are descriptive and concise.

3. Using Design Tokens

Strict adherence to the design token system is paramount. Always use semantic design tokens (e.g., var(--space-4), var(--accent)) instead of raw pixel values or hardcoded colors. Refer to uiux-tokens.md for the complete token architecture and available tokens. This ensures brand consistency and easy theming.

/* GOOD: Using a semantic design token for spacing */
.my-component {
  padding: var(--space-4);
  background-color: var(--surface);
}

/* BAD: Hardcoded values */
.my-component {
  padding: 16px;
  background-color: #FFFFFF;
}

4. Updating AGENTS.md

After creating a new rule file, you MUST update AGENTS.md to include it in the RULE FILES table. This ensures that AI agents are aware of the new rule and can load it when relevant. Add an entry with the file name, a brief description of its contents, and when it should be loaded.

| File               | Contents                                     | Load when          |
|--------------------|----------------------------------------------|--------------------|
| `uiux-new-rule.md` | Guidelines for implementing new UI patterns. | New UI patterns    |