docs(design): Repo Taste — reusable design skill for Codex and Claude

.agents/skills/repo-taste/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: repo-taste
+description: Apply repo.ing's deliberate dark, tactile, lightly retro design language to frontend work without breaking financial truth, identity, accessibility, or live functionality. Use for UI design, review, restyle, UX polish, component creation, dashboards, launch screens, and trading screens.
+---
+
+# Repo Taste — frontend design skill
+
+This is a product-specific art director and quality gate, NOT a permission to redesign the product or change financial behavior.
+
+## Read first
+1. design/repo-taste/CORE.md — portable taste principles and decision order.
+2. design/repo-taste/profiles/repoing.md — actual brand, existing code, assets, and design exceptions.
+3. design/repo-taste/REVIEW.md — before/after visual and functional acceptance.
+
+For a different product, replace the repo.ing profile with that product's own approved profile. Never carry over Repo Cat or repo.ing's colours automatically.
+
+## Workflow
+1. Inventory the route, the user's primary task, real data, existing components, theme tokens, imagery, and responsive behavior. Preserve the current screen in screenshots before editing.
+2. State one screen question and one product-specific visual device. Produce a compact change plan naming files and protected flows.
+3. Work in the existing Next.js/React/CSS stack. Keep all routes, wallet state machines, onchain read semantics, formatting, API contracts, and claims/trading safeguards intact.
+4. Prefer the existing CSS variables and brand assets. Make a screen legible and trustworthy first; retro texture and motion are second-layer accents.
+5. Test visible empty, loading, delayed, error, disconnected, and confirmed states without inventing market activity or balances.
+6. Inspect actual browser output at 1440, 768, and 390 px, dark and light if supported. Review the screenshots, fix the three largest issues, and repeat up to three rounds.
+7. Report what changed, proof collected, remaining defects, and any tests/checks not run.
+
+## Optional upstream skill
+If Leonxlnx/taste-skill is installed, use design-taste-frontend as a SECONDARY tool. For real app screens choose its --app workflow and --keep palette,type. Use its browser inspector when possible, and document narrow, intentional exceptions for repo.ing's monospace, grid, borders, soft radii, and existing brand motion. Do not let its generic house rules overwrite this project's identity.
+
+## Stop conditions
+Do not claim visual verification without seeing the rendered screenshots. Do not fabricate market numbers, simulate a successful signing flow, alter buy/sell or settlement code as a visual cleanup, or deploy/merge without an explicit task.

.claude/skills/repo-taste/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: repo-taste
+description: Apply repo.ing's deliberate dark, tactile, lightly retro design language to frontend work without breaking financial truth, identity, accessibility, or live functionality. Use for UI design, review, restyle, UX polish, component creation, dashboards, launch screens, and trading screens.
+---
+
+# Repo Taste — frontend design skill
+
+This is a product-specific art director and quality gate, NOT a permission to redesign the product or change financial behavior.
+
+## Read first
+1. design/repo-taste/CORE.md — portable taste principles and decision order.
+2. design/repo-taste/profiles/repoing.md — actual brand, existing code, assets, and design exceptions.
+3. design/repo-taste/REVIEW.md — before/after visual and functional acceptance.
+
+For a different product, replace the repo.ing profile with that product's own approved profile. Never carry over Repo Cat or repo.ing's colours automatically.
+
+## Workflow
+1. Inventory the route, the user's primary task, real data, existing components, theme tokens, imagery, and responsive behavior. Preserve the current screen in screenshots before editing.
+2. State one screen question and one product-specific visual device. Produce a compact change plan naming files and protected flows.
+3. Work in the existing Next.js/React/CSS stack. Keep all routes, wallet state machines, onchain read semantics, formatting, API contracts, and claims/trading safeguards intact.
+4. Prefer the existing CSS variables and brand assets. Make a screen legible and trustworthy first; retro texture and motion are second-layer accents.
+5. Test visible empty, loading, delayed, error, disconnected, and confirmed states without inventing market activity or balances.
+6. Inspect actual browser output at 1440, 768, and 390 px, dark and light if supported. Review the screenshots, fix the three largest issues, and repeat up to three rounds.
+7. Report what changed, proof collected, remaining defects, and any tests/checks not run.
+
+## Optional upstream skill
+If Leonxlnx/taste-skill is installed, use design-taste-frontend as a SECONDARY tool. For real app screens choose its --app workflow and --keep palette,type. Use its browser inspector when possible, and document narrow, intentional exceptions for repo.ing's monospace, grid, borders, soft radii, and existing brand motion. Do not let its generic house rules overwrite this project's identity.
+
+## Stop conditions
+Do not claim visual verification without seeing the rendered screenshots. Do not fabricate market numbers, simulate a successful signing flow, alter buy/sell or settlement code as a visual cleanup, or deploy/merge without an explicit task.

AGENTS.md

@@ -0,0 +1,9 @@
+# Agent guidance for repo.ing
+
+For frontend design, UI review, visual polish, copy/layout work, or component restyling, use the repo-taste skill in .agents/skills/repo-taste/SKILL.md. Its portable principles, repo.ing profile and visual verification are under design/repo-taste/.
+
+The project is a real financial application. Design work must preserve canonical repository identity, real chain-derived figures, fee/reward accounting, wallet prompts, slippage, signing, and trade/claim/launch safety checks. Do not modify transaction, settlement, custody, authorization, API, or production controls as part of a cosmetic task.
+
+Use the existing stack, theme tokens, typography, and official brand assets. Keep working light/dark themes. Do not invent Repo Cat variants, claims of verified data, user balances, trading history, or proof.
+
+For other engineering work, follow the relevant existing documentation and tests. This guidance does not authorize production deployment, main-branch merges, or onchain actions.

CLAUDE.md

@@ -0,0 +1,7 @@
+# Claude Code guidance for repo.ing
+
+When the task concerns visual design, frontend UI, page review, interaction polish, layouts, or design-system work, invoke /repo-taste or read .claude/skills/repo-taste/SKILL.md, then design/repo-taste/CORE.md, design/repo-taste/profiles/repoing.md and design/repo-taste/REVIEW.md.
+
+Keep the existing Next.js stack and the repo.ing product identity. Visual tasks are not authorization to edit financial logic, wallet signing, token launches, fees, claims, custody, risk checks, or deployment. Never replace real market data with invented numbers.
+
+Use browser screenshots for before/after claims and be explicit when browser inspection is unavailable. This file only adds design-task guidance; the existing engineering and security documents still govern all other work.

design/repo-taste/BRIEF.md

@@ -0,0 +1,32 @@
+# Reusable agent brief
+
+Use this inside Codex or Claude Code when requesting UI changes. Complete only the fields that matter; the agent should derive known values from the repository.
+
+~~~text
+Use the repo-taste skill.
+
+Project/profile: repo.ing (design/repo-taste/profiles/repoing.md)
+Route or component:
+Primary user:
+One job to complete:
+Current problem:
+Must preserve:
+Relevant approved reference artwork/screenshots:
+Success condition:
+
+First inventory the real page, source tokens, data and states. Capture a before image where possible. Propose a concise direction; then implement the smallest cohesive improvement while leaving trading, auth, fees, launch and claim behavior untouched. Visually review at 1440, 768 and 390, dark/light, critique the top three problems and fix them. Show real screenshots, tests run and limitations. No production deploy or merge.
+~~~
+
+## Blank profile for another product
+
+A new project's profile should identify:
+- Product purpose, user and dominant action.
+- Current code/framework, fonts and token source files.
+- Actual colour roles in both themes; asset filenames and licence/reference provenance.
+- Signature object, visual texture, character and motion limits.
+- Routes and page-vs-app classification.
+- Product data, source-of-truth and restricted operations.
+- Known good reference screenshots; explicit anti-examples.
+- Three initial routes to improve and objective release checks.
+
+The PORTABLE CORE is shared. Each product has a separate PROFILE. Do not homogenise Colony.fun, FYNCH and repo.ing by inheriting the same visual skin.

design/repo-taste/CORE.md

@@ -0,0 +1,49 @@
+# Portable taste principles
+
+## Working definition
+
+An excellent interface feels specific to the thing it serves. Avoid the generic recipe of centered hero + pills + icon cards + lavender glow, but also avoid replacing it with empty minimalism. Each screen must contain the product's actual subject, task, and evidence.
+
+## The six laws
+
+### 1. One job is dominant
+Write one sentence before building: **The visitor came here to [job] and needs to know [fact] before taking [action].** The largest visual element answers that sentence. Secondary blocks answer distinct follow-up questions. No repeated dashboard KPI cards merely to occupy space.
+
+### 2. Authenticity beats decoration
+Inventory 8–12 objects, constraints, people, numbers, product rituals, and image assets unique to the project. Use these to design a visual device that a competitor could not simply rebrand. Render real product data where available; clearly label fixtures in local-only mockups. Never invent customers, onchain numbers, returns, volume, badges, quotes, or signing success.
+
+### 3. Three visual brightness tiers
+Keep a ground, raised/active surfaces, and primary ink hierarchy. A single action colour should indicate the next move. Status colours must express actual meaning (success, warning, danger), not decorate unrelated cards. Secondary copy stays readable. Support a project's existing light theme when it has one.
+
+### 4. Tactile, not noisy
+Offer small satisfying press/hover/focus feedback, rounded hit targets where brand-approved, and a cohesive easing curve. Pixel/CRT/dither treatment is permitted on a mascot, illustration, poster, easter egg, or restrained background. Never put scanlines or texture over figures, charts, labels, input fields, warnings, or wallet consent. No infinite bounce on a primary decision control.
+
+### 5. Characters have identity
+Use approved source artwork, with fixed anatomy, face, silhouette, proportions, crop and colours. Do not generate a new mascot because a placeholder is missing. Do not add fingers or humanlike hands to a brand character whose approved references lack them. Prioritise supplied images over SVG caricatures or generic emoji. Respect asset/licence provenance.
+
+### 6. Inspect the thing people use
+At desktop and phone widths, verify real content, overflow, contrast, focus, states and primary action reachability. Beautiful code with a broken render fails. Three screenshot-led improvement rounds maximum, largest defects first.
+
+## Design primitives
+
+- **Typography:** One strong headline voice plus one readable utility/data voice. Monospace is encouraged for actual identifiers, code, tabular numbers, and brands that deliberately use it; don't let decorative tracking shrink essential figures. Aim for visibly different primary/secondary levels, not six near-identical sizes.
+- **Spacing:** Consistent outer edges. Dense screens stay dense when the task needs scanning. Avoid accidental gaps, orphan cards and giant blank areas. Compact tables need aligned figures, adequate row targets, headers and a mobile alternative.
+- **Forms and actions:** One clear primary action. Keep labels near their controls, real errors near their fields, confirmation states distinct, and dangerous decisions reversible or clearly gated when the product supports it.
+- **Charts:** No ornamental invented lines. Preserve units, time ranges, source freshness, empty history, uncertainty and accessible tabular or textual alternatives. Data takes priority over colour effects.
+- **Motion:** Transform/opacity first; provide prefers-reduced-motion behavior and static fallbacks. No motion that hides content if JavaScript fails or changes transaction meaning.
+- **Responsive:** Compose for 1440, 768 and 390 px; no sideways document scroll, tiny chart labels, cut-off balances or inaccessible wallet actions.
+- **Copy:** Plain, specific, short and evidence-led. Do not imply endorsement of community-launched markets, guaranteed fees, or that a user has signed before a confirmed result.
+
+## Decision sequence for agents
+
+1. Inventory the route, source code, task, actual available assets, and states.
+2. State one screen question and one uniquely owned art-direction idea.
+3. Identify existing patterns and choose what to keep.
+4. Draft a restrained change plan showing exact affected files and protected flows.
+5. Implement the smallest cohesive set of changes within the existing stack.
+6. Run relevant tests and inspect real screenshots.
+7. Fix the three largest user-visible issues; report evidence, not confidence adjectives.
+
+## Never as a side effect of visual work
+
+No migrations, key/credential changes, wallet provider rewrites, balance aggregation changes, price calculation changes, quote/fee/slippage changes, fee withdrawal or buyback automation, transaction submission, custody, live deploy, or main-branch merge. Those require a separately scoped engineering task and its own proof.

design/repo-taste/README.md

@@ -0,0 +1,35 @@
+# Repo Taste
+
+A reusable art-direction and UI-verification system, starting with repo.ing. It encodes the difference between **our intended aesthetic** and any coding model's default UI preferences. This is documentation and agent guidance; it does not modify the running site.
+
+## The idea
+
+**Soft controls. Sharp information. A little old-internet magic.**
+
+Build interfaces that feel authored and alive without making financial facts hard to read. The mascot, type, rhythm, and tiny tactile interactions make the product recognisable; users still get a clear answer, clear status, and a safe next action.
+
+## Contents
+
+- CORE.md — portable decisions, brand inheritance, interaction and content rules.
+- profiles/repoing.md — repo.ing's current design assets, colours, type, route-specific direction, and non-negotiables.
+- tokens/repoing.css — opt-in reference aliases for existing token names; NOT imported into the site.
+- REVIEW.md — browser, accessibility, data-truth and interaction quality gates.
+- BRIEF.md — reusable prompt for a design task and a blank project-profile starter.
+- .agents/skills/repo-taste/SKILL.md — Codex/agent entry point.
+- .claude/skills/repo-taste/SKILL.md — Claude Code entry point.
+
+## Use
+
+In the repo root, ask Codex to **use repo-taste to audit and polish /explore**, or ask Claude Code **/repo-taste audit and polish /explore**. Scope one route or component at a time. The skill first records the original, inventories the real data and assets, edits minimally, then verifies the rendered result at three widths.
+
+If the upstream Taste Skill is also installed, its --app draw and inspector can supply composition options and automated browser checks. Its general anti-slop bans are NOT higher priority than the repo.ing profile. Preserve sanctioned monospace, borders, soft interactions and existing brand textures; justify exceptions individually.
+
+This first version intentionally ships **design instructions only**, not a site redesign. There are no claims of completed browser screenshots or changed production UI.
+
+## Port to another project
+
+Copy CORE.md and REVIEW.md, then create a project-specific profile documenting the real UI, current files, palette, fonts, art assets, permitted style and forbidden changes. Copy one or both skill entry points and update the profile path. Do not copy Repo Cat, colours or token values into FYNCH/Colony/Burrow unless they belong to that brand.
+
+## Precedence
+
+Financial and security correctness > real data and accessibility > established brand identity > the task brief > optional taste-skill defaults. An attractive screenshot never justifies changing account state, prices, fees, trade preflight, signatures, or consent.