@trading-game/design-intelligence-layer 0.8.5

package/docs/accessibility-standards/trading-game-accessibility-standards.md

@@ -0,0 +1,101 @@
+# trading.game — Accessibility Standards
+
+*Inclusion standards and intent for designers and AI agents.*
+
+Version 1.0 · March 2026
+
+---
+
+## What this is
+
+trading.game is built for everyone — no finance degree required. That promise only holds if the product is genuinely usable by everyone, including people who navigate differently, see differently, or process information differently.
+
+This document is not a technical spec. The Design System Guide and npm package handle implementation. This document sets the intent — the human standard every screen should meet, regardless of how it was built.
+
+Target standard: **WCAG 2.1 Level AA**.
+
+---
+
+## The people we design for
+
+Accessibility is not an edge case. At any given moment, our players include people who:
+
+- Navigate entirely by keyboard, with no mouse
+- Use a screen reader that reads the interface aloud
+- Cannot distinguish between red and green
+- Are sensitive to flashing or fast-moving animation
+- Are playing one-handed, or on a small screen in bright sunlight
+- Are new to trading and need extra clarity to feel confident
+
+Good accessibility often makes the experience better for everyone, not just those who need it most.
+
+---
+
+## The standards
+
+### Colour never carries meaning alone
+
+Colour supports understanding — it never carries it alone. This matters most in trading contexts where green and red signal wins, losses, and balance changes. Any player who cannot see or distinguish colour should receive the same information as everyone else — through a number, a sign, an icon, or a word alongside it.
+
+---
+
+### Every player can navigate freely
+
+The experience should be fully reachable regardless of how a player interacts with their device. Navigation should feel logical and follow the natural flow of the screen.
+
+---
+
+### Every element communicates its purpose
+
+Interactive elements should be understandable in isolation — not just visually, but to anyone experiencing the interface through assistive technology.
+
+---
+
+### Live information reaches everyone
+
+trading.game is a live product. Prices move, trades resolve, balances change. Players who rely on assistive technology should stay as informed as anyone else in real time.
+
+---
+
+### Animation enhances — it never replaces
+
+Animation is part of the trading.game identity. The words and outcomes always stand on their own. Animation is the layer on top that makes moments feel bigger. For players who need less motion, the experience should remain complete.
+
+---
+
+### Content stays readable under any conditions
+
+The interface should hold up when players adjust their device settings — larger text, higher contrast, different display conditions. Information should always be accessible, never hidden by how it's presented.
+
+---
+
+### Trade actions need generous targets
+
+trading.game involves real money. Buttons that place or confirm a trade should be large enough that a player cannot easily tap the wrong one. The financial consequence of a mistap is real — size and spacing matter more here than anywhere else in the product.
+
+---
+
+### Irreversible actions need confirmation
+
+Placing a trade, cashing out, or any action a player cannot undo should always require a deliberate second step. One tap should never be enough to execute something with financial consequences. The confirmation moment is also a trust moment — it tells the player the product takes their money seriously.
+
+---
+
+## Agent checklist
+
+Run before completing any screen.
+
+- [ ] Colour is never the only way information is communicated
+- [ ] Every interactive element is reachable without a mouse
+- [ ] Navigation follows a logical order that matches the screen
+- [ ] Every interactive element communicates its purpose without relying on visuals alone
+- [ ] Live updates are reachable by assistive technology
+- [ ] Animation is an enhancement — outcomes are clear without it
+- [ ] Content holds up when device display settings are adjusted
+- [ ] Trade action targets are large enough to prevent mistaps
+- [ ] Irreversible trade actions require a confirmation step
+
+---
+
+*trading.game Accessibility Standards — v1.0*
+*Cross-reference: Design System Guide, Content Style Guide, Design Principles*

package/docs/design-principles/trading-game-design-principles.md

@@ -0,0 +1,97 @@
+# trading.game — Design Principles
+
+*High-level product design guidance for designers and AI agents*
+
+Version 1.0 · March 2026
+
+---
+
+trading.game makes trading feel faster, simpler, and more exciting — without losing the confidence and seriousness that financial products require. These principles define the design personality of the product and guide how AI agents apply components, layouts, motion, copy, and brand assets. This is not a style guide. It is a decision framework — giving AI enough direction to design with the right taste, energy, and priorities without over-constraining creativity.
+
+---
+
+## How AI agents should use this
+
+- Treat these principles as a decision framework, not a checklist
+- Adapt emphasis, hierarchy, density, and motion before inventing new patterns
+- When unsure, reduce friction before adding flair
+
+---
+
+## Core principles
+
+### 1. Trading first
+
+Every screen should make trading feel central. Game mechanics, rewards, and visual excitement should support the trading journey, not compete with it.
+
+*Agent guidance:* Prioritise price, action, progress, outcome, and decision-making signals. Entertainment should sharpen focus, not pull attention away from the core task.
+
+---
+
+### 2. Simple by default
+
+Complexity must be absorbed by the interface, not pushed onto the user. The product should feel easy to enter, easy to scan, and easy to act on.
+
+*Agent guidance:* Reduce visible choices, sequence decisions clearly, and reveal more only when needed. Make the next step obvious.
+
+---
+
+### 3. Clean and focused
+
+The UI should feel lightweight, modern, and intentional. Nothing should look cluttered, accidental, or overworked.
+
+*Agent guidance:* Give content room, keep hierarchy obvious, and let one key action or message lead each view.
+
+---
+
+### 4. Excitement with control
+
+The experience should have energy, pace, and momentum — but never feel noisy or chaotic. Excitement should come from progress, timing, and feedback.
+
+*Agent guidance:* The product should feel alive and responsive — every action produces a reaction. Use motion, contrast, and celebration selectively. Keep the core experience calm enough for confident decisions.
+
+---
+
+### 5. Fun, not childish
+
+trading.game should feel playful, rewarding, and fresh — but never gimmicky. It should win through confidence and smart interaction design, not novelty for novelty's sake.
+
+*Agent guidance:* Favour sophistication over cartoon behaviour. Keep the tone upbeat but grounded.
+
+---
+
+### 6. Reward progress
+
+The experience should make users feel movement, mastery, and achievement. Good design creates momentum and helps users feel better the more they use it.
+
+*Agent guidance:* Surface progress, completion, milestones, and positive feedback in a clear, motivating way.
+
+---
+
+### 7. Trust in every detail
+
+Because this is trading, the product must feel dependable at all times. Accuracy, transparency, and professionalism are non-negotiable.
+
+*Agent guidance:* Make balances, status, outcomes, pricing, timing, and risk cues clear. Avoid visual tricks or playful treatment of serious information.
+
+---
+
+### 8. Consistency creates fluency
+
+Users should quickly learn how the product behaves and feel faster with every interaction. Familiar patterns build confidence.
+
+*Agent guidance:* When a pattern already exists in the product, use it. Consistency is not a constraint — it is how the product earns trust over time. Novelty should only enter when it genuinely improves the experience, not for variety's sake.
+
+---
+
+## Checklist
+
+Run this before completing any screen or feature.
+
+- [ ] This screen feels like trading.game — not generic
+- [ ] Trading is still the hero — game elements support, not distract
+- [ ] The next action is obvious without explanation
+- [ ] Energy comes from the experience, not decoration
+- [ ] Serious information is treated seriously
+- [ ] A first-time user would understand this without instructions
+- [ ] One pattern was reused before a new one was invented