@trading-game/design-intelligence-layer 0.9.0 → 0.9.2

package/guides/brand-voice/trading-game-brand-voice.md

@@ -0,0 +1,325 @@
+# trading.game — Brand voice
+
+**Version:** 2.0 · April 2026
+**Adds:** Channel-specific voice application per persona mode; anti-AI writing rules for all copy
+
+---
+
+## What this document is for
+
+The content style guide covers *what* to write. The personas doc covers *who* you're writing for. The field guide covers what's running in their head when they read it.
+
+This document covers the gap between those three: *how the voice changes by channel and by the mode the player is in when they get there*.
+
+Read the field guide before writing anything player-facing. These personas aren't audience segments; they're states. The same person is an Edge Seeker at 9am, a System Runner by lunchtime, and a Public Predictor the moment they go on a streak. Copy that lands across all three in one sentence is the goal.
+
+---
+
+## The one thing we're selling
+
+Not games. Not a platform. Not a crypto product with a trading UI.
+
+The read.
+
+Specifically: the moment you call what a market does next, and you're right. The line moves. The number hits. You say *I called it.* That sentence belongs to us. No other product gives people a fast, clean, verifiable reason to say it. Polymarket is too slow. CFD platforms are too opaque. Casinos don't let you call anything — they just spin. trading.game resolves in five ticks. That's the whole pitch.
+
+Every headline, button, bust state and push notification either reinforces *I called it* or takes it away. There's no neutral option.
+
+---
+
+## Voice in one sentence
+
+Sound like the sharpest person in the room who actually plays the games and doesn't need you to be impressed by either.
+
+---
+
+## The four brand traits
+
+These come from the content style guide. They're reproduced here so you don't have to switch between docs.
+
+**Instant.** No warm-up. No preamble. Get to the point before the player blinks.
+
+**Alive.** The game has a pulse. Copy responds to what just happened; it never reads like something you could have written last Tuesday.
+
+**Fearless.** No disclaimers in the player's face. No hedging. When something needs to be said, say it clearly.
+
+**For everyone.** The language is never gatekeepy. No jargon without context. A first-time player and someone who's watched charts for five years should both feel like this was built for them.
+
+---
+
+## The three modes — and what to lead with
+
+The player field guide calls these Edge Seeker, System Runner, and Public Predictor. The personas doc calls them the Self-Taught Analyst, the Session Tracker, and the Documented Better. Same three people; the field guide is describing what mode they're *in* when they read your copy.
+
+Here's the shorthand for writing:
+
+**Edge Seeker mode:** They came in with a thesis. Lead with the read, not the platform. The win copy should confirm their judgement. The bust copy should name the market, not the mistake. Never say "your selection was incorrect."
+
+**System Runner mode:** They have rules. The rules are probably wrong. It doesn't matter; the system is the thing that keeps them coming back. Loss copy needs to give the bust a shape, not just a result. Session stats are more compelling to this person than any multiplier graphic. Clean withdrawals are not a feature; they're a minimum bar.
+
+**Public Predictor mode:** They post wins within minutes of calling them. The result screen is a content piece they'll screenshot. Every win state needs: the mechanic, the USDT figure, the streak or record context. If it's generic, it won't get shared. The UI is a distribution channel for their audience.
+
+---
+
+## Copy that works across all three modes
+
+Some copy has to serve the player regardless of which mode they're in when they read it. Bust copy is the best example. Here's the principle from the field guide:
+
+> *"One sentence. Three self-images intact. Player goes again."*
+
+Test any bust state against all three modes. "Bust. Market barely moved. Tight range." does this:
+- Gives the Edge Seeker an external explanation (the market, not their read)
+- Gives the System Runner information to work with (the setup was fine; the range was wrong)
+- Gives the Public Predictor a way to post the loss without looking bad ("setup was right, vol just wasn't there")
+
+Compare that to "Your selection was incorrect." That sentence destroys all three frames simultaneously.
+
+---
+
+## The near-miss — write it specifically
+
+When the price lands one tick short of the target, the brain doesn't register a clean loss. It registers *I was right and the resolution was slightly off.* This is neurologically distinct from a normal bust, and it's more motivating than a win; the tension stays alive.
+
+Near-miss copy should never say the player was wrong. They nearly weren't.
+
+| ✅ | ❌ |
+|---|---|
+| "One tick short. The read was right." | "You missed. Try again." |
+| "55.49. You had 55.50. Next one." | "Incorrect selection." |
+| "Close. Vol reversed at the last second." | "Better luck next time." |
+
+---
+
+## Channel application by mode
+
+In-game copy is covered in the style guide. What follows is everything else: social, email, community, announcements.
+
+---
+
+### X (Twitter/X)
+
+One idea per post. Hook on the first line. Cut early.
+
+The tone is not the same for all three modes. Edge Seekers respond to validation of attention and analysis. System Runners respond to data and provably fair mechanics. Public Predictors respond to things worth posting themselves.
+
+**Writing for Edge Seekers on X:**
+Give them something to be early on. Frame the product as a read, not a game.
+
+> "Vol 100 has been oscillating inside a 12-point range for three sessions.
+> Rise & Fall is pricing that in. If you've been watching it, now's the time."
+
+> "The fastest feedback loop on a market read.
+> Five ticks. Real price data. No waiting for a daily close."
+
+**Writing for System Runners on X:**
+State the mechanics plainly. They'll run their own analysis.
+
+> "House edge: 2%. Fixed. Not variable, not hidden in a spread.
+> Black-Scholes CDF pricing. Payout shown before you commit."
+
+> "Session stats live after every trade.
+> Win rate. Net USDT. Number of trades. That's the data your system runs on."
+
+**Writing for Public Predictors on X:**
+Give them something they'd say. Or something that makes trading.game look good to their followers.
+
+> "7-tick streak on Vol 75.
+> Some people screenshot the win. Some people post the chart."
+
+> "Found this platform three weeks ago. Already at 14-7 on calls.
+> If you want the breakdown, the result screen has everything."
+
+**Formatting rules for X:**
+One emoji at most, only if it earns its place. One hashtag maximum, only if it's genuinely relevant. Sentence case always. No triple punctuation. No ALL CAPS.
+
+---
+
+### LinkedIn
+
+More room, more considered. The same voice; more weight on the intellectual frame. Lead with a genuine insight or a contrarian point, not a product update dressed as thought leadership.
+
+**Good:**
+> "Most trading education teaches theory.
+> trading.game teaches decision-making under uncertainty, in five-second intervals, against a live price feed.
+> Knowing the right move and making it under pressure are different skills. Most platforms only train one of them."
+
+> "Prediction markets beat every major poll in the 2024 US election.
+> The edge wasn't smarter models. It was faster feedback loops. People who were wrong found out sooner, adjusted, and were less wrong next time.
+> That's the whole product we built."
+
+**Bad:**
+> "We're excited to share that trading.game has launched exciting new features! Our innovative platform is disrupting the traditional trading education space with cutting-edge gamification technology..."
+
+One structural rule for LinkedIn: never open with "We're pleased / thrilled / excited to announce." Start with the announcement. If it's good, the announcement earns the excitement. If you have to label your own news as exciting, it probably isn't.
+
+---
+
+### Email
+
+Subject line: short, specific, creates a small tension.
+Body: one thing. Then the action.
+
+Subject lines that work are different by mode:
+
+**Edge Seeker:**
+- "Your read on V_100 paid out."
+- "Rise & Fall is running on Vol 200. Your call."
+- "The chart moved where you said it would."
+
+**System Runner:**
+- "Your session stats: 7 trades, 4 wins."
+- "Withdrawal processed. 90 seconds."
+- "Your system is up 3 this week."
+
+**Public Predictor:**
+- "Streak: 7. Post it."
+- "You were early on that Vol 75 move."
+- "Your all-time record is now 47–29."
+
+**Subject lines that don't work for anyone:**
+- "Exciting updates from trading.game!"
+- "Don't miss out on these amazing new features"
+- "A message from our team 🙏"
+
+**Good email opening (Edge Seeker):**
+> "You called the Vol 75 level three days ago.
+> It hit today. Your trade settled 1.96x.
+> That's what attention looks like."
+
+**Good email opening (System Runner):**
+> "Six sessions in: 4 wins, 2 losses, net +340 USDT.
+> That's above the 50% baseline by enough to matter.
+> Your stats are in the app."
+
+**Good email opening (Public Predictor):**
+> "You hit a 7-game streak yesterday.
+> The result screen's been designed so that screenshot is worth posting. Have a look at it."
+
+**Bad email opening (for anyone):**
+> "Hi [First Name]! We hope you're having a wonderful day! We're reaching out with some exciting news about our platform that we think you'll love..."
+
+---
+
+### Community (Discord / Telegram)
+
+Same voice; slightly more relaxed. Not a different person. The biggest mistake community managers make is treating Discord as "informal" and drifting into hype language that doesn't fit the brand.
+
+What works: talking to the mode the community is in. If there's a hot streak in the channel, the System Runner framing works well. After a rough patch, the Edge Seeker loss framing preserves the most self-images.
+
+**Good:**
+> "Vol 100 has been spiking since the open. If you've been watching it, now you know."
+
+> "Clean withdrawal just confirmed for two people in the thread. USDT, 90 seconds."
+
+> "7-game streak in the channel this morning. Two of you got screenshots worth posting."
+
+**Bad:**
+> "WAGMI fam 🚀🚀🚀 who's been crushing it today??"
+
+> "Don't forget — trading season is HERE and gains are waiting for you bestie!! 💸💸"
+
+The rule: write Discord messages the same way you'd write an X post, then relax the formality by about 10%. Not 50%.
+
+---
+
+### Announcements and product updates
+
+State the thing. Then the implication for the player. Don't lead with your feelings about the announcement.
+
+| ✅ | ❌ |
+|---|---|
+| "Rise & Fall now runs on V_200. Higher vol, wider payout range. Check the multiplier before you trade." | "We're excited to announce an exciting new instrument! Amazing opportunity for all traders!" |
+| "Digits is live. Tick-based prediction on the last digit of a price feed. 1–10 ticks, six contract types." | "Introducing Digits, our innovative new game that revolutionises the prediction experience!" |
+| "Withdrawal processing is now instant. Not 'faster.' Instant." | "We've made some improvements to our withdrawal process for a more seamless experience." |
+
+---
+
+## What we never say
+
+Banned because they're empty, borrowed, or destructive to the player's self-image.
+
+| Never say | Why |
+|---|---|
+| "Exciting" (describing our own things) | Show it; don't label it. |
+| "Innovative" / "cutting-edge" | Claims, not descriptions. The product proves it. |
+| "Seamless" | That's the baseline for anything that works. |
+| "Journey" (as in trading journey) | Soft, vague, and corporate. |
+| "Empowering" / "democratising" | Filler unless it's a mission statement. |
+| "Don't miss out!" | Fake urgency. |
+| "We're thrilled / excited / delighted to announce" | Start with the announcement. |
+| "Lucky break" | Destroys the Edge Seeker's self-image. |
+| "Your selection was incorrect" | Destroys all three modes simultaneously. |
+| "Try again for another chance to win" | It's not a chance; it's a read. |
+| "LFG" / "wagmi" / "gm fren" | Borrowed social credibility from a community we're not part of. |
+| "You're getting the hang of this!" | Implies they didn't already have it. Kills the Public Predictor. |
+| Three consecutive exclamation marks | Once is enough. Rarely. |
+
+---
+
+## Competitive positioning in voice
+
+HyperSwap (@HyperSwapX) operates in adjacent social territory. Their tagline "Trade, Copy. Earn" packs a lot into three words. Their community language ("Swappies," point seasons, NFT allocations to top holders) creates belonging through ownership. They're transparent about tokenomics: "75% of protocol revenue to buyback and burn" states the number without hedging.
+
+What they do well isn't transferable to us. Their belonging mechanics are ownership-based — you're a SWAP holder, an early believer, a governance participant. We don't have a token. Our belonging mechanics are mastery-based. "Your win rate: 54%. The baseline is 50%. You're ahead." is our version of "you're a Swappie." The ledger is skill, not holdings.
+
+The other difference: HyperSwap assumes DeFi fluency. We can't. Some players have never held a token. Copy that assumes otherwise loses them at the first acronym.
+
+| HyperSwap register | trading.game register |
+|---|---|
+| "SWAP Genesis is live. Early believers get rewarded 🔥" | "Rise & Fall is live on V_100. Edge is 2%. The rest is skill." |
+| "Swappies, the airdrop is coming 🚀" | "Your win rate this week: 54%. Baseline is 50%. You're ahead." |
+| "Earn boosted rewards for LPs 💰" | "Transferred 20 USDT to GridRush. Your capital, your call." |
+
+---
+
+## Vocabulary reference
+
+| Use | Not |
+|---|---|
+| trading.game | Trading.Game / Trading Game (always lowercase) |
+| USDT | Dollars, funds, money (use the specific term) |
+| Trade (noun/verb) | Bet, wager, gamble |
+| Contract | Position (in most contexts) |
+| Rise / Fall | Up / Down (in game-specific copy) |
+| Win rate | Success rate |
+| Demo mode | Free play mode (in copy; "free play" is a UI label) |
+| Arena | Dashboard, home screen |
+| Real session | Live session, paid session |
+| Settlement | Resolution, result |
+| Bust | Loss (in in-game copy; elsewhere "loss" is fine) |
+
+### Game names — exact
+
+| Correct | Not |
+|---|---|
+| Rise & Fall | Rise and Fall / Rise/Fall |
+| GridRush | Grid Rush / Grid rush |
+| Swipe Cards | Swipe-Cards / SwipeCards |
+| Digits | The Digits game |
+| Dice | The Dice game |
+
+### Formatting
+
+- USDT amounts: `340 USDT` not `$340` (USDT is the platform currency)
+- Percentages: `2%` not `2 percent`
+- Win multipliers: `1.96×` with the multiplication symbol, not `1.96x`
+- Tick counts: `5 ticks`, `1 tick` in UI; spell out in prose ("five ticks")
+
+---
+
+## Quick-reference checklist
+
+Before publishing anything:
+
+- [ ] Would "your selection was incorrect" be better? If so, rewrite it.
+- [ ] Which mode is the player likely in when they read this? Does the copy protect that self-image?
+- [ ] Any banned phrase? (exciting, innovative, seamless, journey, LFG, lucky break)
+- [ ] More than one exclamation mark? Cut to zero.
+- [ ] Does it land the point in the first sentence?
+- [ ] Correct game name formatting?
+- [ ] Is it shorter than it needs to be?
+- [ ] Does it sound like trading.game, or could it belong to any product?
+
+---
+
+*trading.game Brand Voice — v2.0*

package/guides/design-system-guide/trading-game-ds-guide.md

@@ -36,7 +36,7 @@ NEVER use:
 
 ALWAYS use semantic tokens:
   ✅ bg-prominent, bg-card, bg-popover, bg-subtle, bg-overlay
-  ✅ text-on-prominent, text-on-subtle, text-on-muted
+  ✅ text-on-prominent, text-on-subtle
   ✅ border-border-subtle, border-border-prominent, ring-ring
   ✅ bg-primary, bg-primary-hover, bg-secondary-hover
   ✅ text-semantic-win, text-semantic-loss, text-semantic-warning
@@ -151,7 +151,6 @@ import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
 | `--on-prominent`                | `text-on-prominent`                     | Primary text (headings, body) |
 | `--on-prominent-static-inverse` | `text-on-prominent-static-inverse`      | Always-white text (e.g. on primary blue buttons) |
 | `--on-subtle`                   | `text-on-subtle`                        | Secondary text (descriptions, labels) |
-| `--on-muted`                    | `text-on-muted`                         | Tertiary text (subtle labels, placeholders) |
 
 ### 2.5 — Borders & Inputs
 
@@ -281,7 +280,7 @@ import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
 | Color an elevated surface (popover)    | `bg-popover`                      | `bg-card` for popovers                 |
 | Write primary heading text             | `text-on-prominent`               | Pure white, raw hex colors             |
 | Write body / description text          | `text-on-subtle`                  | `text-on-prominent` for descriptions   |
-| Write a subtle label                   | `text-on-muted`                   | `text-on-subtle` for the subtlest text |
+| Write a subtle label                   | `text-on-subtle`                  | Raw gray values                        |
 | Add a default border                   | `border-border-subtle`            | Solid black borders, `border-border`   |
 | Add a strong border                    | `border-border-prominent`         | —                                      |
 | Style an input (resting)               | `border-input`                    | Solid colored backgrounds              |
@@ -423,8 +422,8 @@ All buttons: `font-display font-bold`, sentence case (no `uppercase`, no `tracki
 | Hover    | Color shift per variant (see above)              |
 | Focus    | 3px ring with `ring-ring/50` opacity             |
 | Pressed  | `active:opacity-60`                              |
-| Loading  | `opacity-50`, `pointer-events-none`, `data-loading`, `aria-busy` |
-| Disabled | `opacity-50`, `pointer-events-none`              |
+| Loading  | `opacity-24`, `pointer-events-none`, `data-loading`, `aria-busy` — applies to all variants (primary, secondary, tertiary) |
+| Disabled | `opacity-24`, `pointer-events-none` — applies to all variants (primary, secondary, tertiary) |
 
 ---
 
@@ -546,6 +545,7 @@ import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, Dialog
 | Slider | [simple] | — |
 | Sonner (Toaster) | [simple] | — (also import `toast` from `sonner`) |
 | Spinner | [simple] | — |
+| Stepper | [simple] | — |
 | Switch | [simple] | — |
 | Table | [composed] | TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, TableCaption |
 | Tabs | [composed] | TabsList (`variant`: default/line, `size`: sm/md/lg), TabsTrigger (`iconPosition`: inline/top), TabsContent. Root accepts `orientation`: horizontal/vertical. |
@@ -571,6 +571,7 @@ These are styling behaviors you can't discover from TypeScript types alone:
 | Select | Item hover: `bg-primary/[0.08]`. Selected: `text-primary font-medium` + checkmark. `SelectTrigger` accepts `readOnly` prop: blocks interaction, retains full default appearance, chevron renders at `opacity-30` |
 | Progress | Track: `bg-primary/20`. Indicator: `bg-primary`. Radius: `rounded-2xs` |
 | Spinner | Inherits parent text color. **Always pass `text-primary` for standalone use** |
+| Stepper | Numeric input flanked by `−` / `+` tertiary `icon-xs` buttons. Composes `InputGroup` internally. Props: `value`, `defaultValue`, `onValueChange`, `min`, `max`, `step` (default 1), `disabled`, `placeholder`. Supports controlled & uncontrolled modes, keyboard Arrow Up/Down, and floating-point steps. Default width: `w-32` |
 | Switch | Checked track: `bg-slider-range`. Checked thumb: `bg-primary` |
 | Slider | Thumb: square `rounded-[4px]`, `bg-primary`. Track range: `bg-slider-range` |
 | Dialog/Sheet | Footer buttons should use `size="md"`. Overlay: `bg-overlay` |
@@ -628,7 +629,7 @@ Landing page hero sections in multiple layout types.
 | Using `border-border` | Use `border-border-subtle` or `border-border-prominent` |
 | Using `bg-hover` | Use `bg-primary/[0.08]` or `bg-secondary-hover` |
 | Using `text-primary-foreground` | Use `text-on-prominent-static-inverse` |
-| Using `text-on-decorative` | Use `text-on-muted` |
+| Using `text-on-decorative` | Use `text-on-subtle` |
 | Using `font-mono` expecting Plus Jakarta Sans | Use `font-display` or `font-body` |
 | Using `font-bold` for headings | Use `font-semibold` (600) for headings |
 | Using `uppercase` on buttons | Buttons use sentence case (no `uppercase`) |
@@ -645,7 +646,7 @@ Landing page hero sections in multiple layout types.
 
 1. **Primary blue text on white** (~3.0:1) — reserve for large/bold UI labels only.
 2. **Secondary text `text-on-subtle` on white** (~4.5:1) — meets WCAG AA for normal text.
-3. **Tertiary text `text-on-muted` on white** (~7.0:1) — safe for all sizes.
+3. **Secondary text `text-on-subtle` on white** (~4.5:1) — meets WCAG AA for normal text.
 4. **Win green on white** (~5.0:1) — safe for normal text at AA.
 5. **Loss red on white** (~3.9:1) — use at 18px+ bold or pair with icons.
 6. Always pair semantic colors with **icons or labels** — never communicate meaning through color alone.

package/guides/rules/design-system-consuming-project.mdc

@@ -70,7 +70,7 @@ import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
 ✅ text-on-prominent                — primary text (black #000000)
 ✅ text-on-prominent-static-inverse — always white — for text on dark/primary bg
 ✅ text-on-subtle                   — secondary text (mid grey)
-✅ text-on-muted                    — low emphasis text (dark grey)
+
 ✅ text-primary                     — brand blue #2323FF
 ✅ text-semantic-win                — green — profit/positive
 ✅ text-semantic-loss               — red — loss/negative

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trading-game/design-intelligence-layer",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Trading Game Design System — shadcn/ui components with Tailwind CSS v4",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/styles.css

@@ -51,7 +51,7 @@
   --color-alert-info-border: var(--alert-info-border);
   --color-alert-error-text: var(--alert-error-text);
   --color-alert-error-border: var(--alert-error-border);
-  --color-on-muted: var(--on-muted);
+
   --color-overlay: var(--overlay);
   --color-slider-range: var(--slider-range);
   --color-semantic-info: var(--semantic-info);
@@ -242,7 +242,7 @@
   --primary-hover: oklch(0.403 0.251 267.5);
   --subtle: oklch(0.96 0 0);
   --on-subtle: oklch(0.52 0 0);
-  --on-muted: oklch(0.38 0 0);
+
   --border-subtle: oklch(0.92 0 0);
   --border: var(--border-subtle);
   /* @deprecated alias — use --border-subtle or --border-prominent */