UX Starter Kit

Everything here is plain markdown. No special tools. Use these files with Claude, ChatGPT, Cursor, Copilot — whatever you already use. Drop them in a repo, a shared folder, or just paste them into a conversation.

The idea is simple: AI gives you generic output because it doesn't know anything about your team, your users, or your standards. These files fix that. Write down what your team knows, give it to the AI, and the output gets specific.

This comes from how we work at Goose Group. We wrote more about why this matters in our tastemaking guide, and we built Smaak to do it at scale. But a well-written markdown file does 80% of the work. Start here.

What's in the kit

lime-ux/
├── TASTE.md              ← how your team thinks about UX
├── context/
│   ├── rider.md          ← what you know about riders
│   ├── supply-ops.md     ← what you know about ops
│   └── research.md       ← key findings from user research
├── system/
│   └── service-blueprint.md ← how Lime actually works
└── skills/
    └── design-critique.md ← one reusable AI workflow

Two things make everything else work: TASTE.md (how your team thinks) and service-blueprint.md (how Lime's system actually works). Together they give AI — and new team members — everything they need.

File 1: TASTE.md

This is the main one. It captures what your team believes, what you refuse to do, and what "good" means to you. Fill it in, then paste it at the start of any AI conversation: "Read this first. This is how our team thinks."

# Lime UX — How We Think

## What we believe about good UX

[Write 3-5 things that actually shape your decisions.
Not "we value good design" — that doesn't help AI
or anyone else. The specific stuff matters.]

Examples to get you started:
- "Clarity over cleverness. If a rider has to think about
  what to do next, we failed."
- "Real-world context matters more than screen context.
  A rider is standing on a sidewalk in the rain.
  Design for that."
- "Consistency across markets matters, but local reality
  wins when they conflict."


## What we don't do

[These are the things your team pushes back on.
The stuff you reject in design reviews.
Write them as clear rules.]

- Don't hide critical information behind progressive disclosure
- Don't use placeholder copy in specs — real copy reveals
  real design problems
- Don't design flows that assume reliable connectivity
- [What else? What do you always say no to?]
- [What "best practices" does your team reject?]


## How AI should work with us

[This tells AI how to behave when working with your team.]

- When reviewing a design, always consider: edge cases,
  failure states, accessibility, and market differences
- When something is unclear, ask — don't guess
- When a decision needs empathy or taste, say so:
  "this needs a human call" — don't just pick one
- Push back when something feels generic. We'd rather
  hear "this could be any company's design" than get
  a polite thumbs-up
- Use our specific principles, not general UX heuristics


## Our world

We work across different contexts with different rules.

### Rider side
- [What matters when designing for riders?]
- [What real-world stuff shapes rider UX?
  Weather, parking rules, vehicle types, safety...]
- [What do riders actually do vs. what we assume?]

### Supply / Ops side
- [What matters when designing for ops teams?]
- [What constraints do warehouse/fleet people have?]
- [What are the weird rules that only people
  who work in ops know about?]


## What good looks like

[Paste real examples. These teach AI more than
any instruction you could write.]

### This is good work:
- [Paste a real spec, critique, or decision rationale
  your team is proud of. What makes it good?]

### This missed:
- [Paste something that was too generic, too shallow,
  or ignored important context. What was wrong?]

How to use it: Paste this at the start of any AI conversation before you ask for help. That's it. Try it once with a real task and see the difference.

File 2: context/rider.md

Everything your team knows about the rider side that lives in people's heads instead of in a doc. The weird rules. The stuff that only comes up when you've been doing this for a while.

# What we know about riders

## Who they are
- [Demographics, behaviors, mental models]
- [What riders care about. What they don't.]

## What the real world is like
- [Weather, time of day, connectivity, physical context]
- [How riding in Berlin is different from Austin or Paris]
- [Seasonal stuff that changes flows]

## The weird rules
- [Market-specific regulations that affect design]
- [E-bikes vs. scooters — what's different?]
- [Edge cases that matter a lot when they happen]

## What research told us
- [Key findings — link or paste]
- [Direct quotes from riders. These are gold for AI —
  a real quote calibrates output better than a summary]

## Why we made past decisions
- [Why did we do X instead of Y?]
- [What did we try that didn't work?]
- [What constraints shaped the design?]

File 3: context/supply-ops.md

Same thing, different world. Ops has its own users, its own pressures, its own weird rules.

# What we know about supply / ops

## Who the users are
- [Warehouse staff, fleet managers, city ops teams]
- [What their day actually looks like]
- [What tools they already use]

## What their world is like
- [Shift patterns, vehicle maintenance]
- [What breaks when things go wrong?]
- [Normal day vs. bad day — what's different?]

## The weird rules
- [Market-specific regulations]
- [Vehicle handling differences]
- [Seasonal changes to operations]

## Key workflows
- [What do ops people do all day?]
- [Where are the bottlenecks?]
- [What's manual that probably shouldn't be?]

## What we've heard from them
- [Quotes from ops users]
- [What they say vs. what they actually do]

File 4: system/service-blueprint.md

This is the other half of the picture. TASTE.md says how your team thinks. This doc maps how Lime's system actually works — the real flows, the state machines, the places where humans and software meet.

Building this is a project in itself, but it's one person, a few days, and it's incredibly valuable. Use Claude Code to inspect the backend repos. Map the states and transitions. Then connect them to the physical world.

# How Lime Actually Works

## How to build this doc

Use Claude Code (or any agent with codebase access) to
inspect the backend. Ask it to trace the flows:

  "How does a ride work end-to-end? What are the states?
   What triggers each transition? Where do humans intervene?"

Then map it to the physical world — what's actually happening
with the rider, the bike, the ops team at each stage.

## Rider flow (example — fill in from your system)

<!-- Mermaid charts render in GitHub, Notion, many tools -->

```mermaid
stateDiagram-v2
    [*] --> Searching : rider opens app
    Searching --> Reserved : rider selects bike
    Reserved --> Riding : rider unlocks
    Riding --> Parked : rider ends ride
    Parked --> Available : system confirms parking
    Parked --> FlaggedParking : bad location detected
    FlaggedParking --> OpsReview : ops team notified
    OpsReview --> Available : ops resolves
```

[Map each state to a Figma screen or flow if you have one]
[Note where the system and physical world meet]

## Where humans are in the loop

[This is the service blueprint part]

- Rider: [what decisions does the rider make?]
- Ops team: [when do they intervene? what triggers it?]
- Maintenance: [what's the cycle? what are the triggers?]
- Support: [when does a human get involved?]

## The weird transitions

[Edge cases, market-specific differences, seasonal changes]
[The stuff that only shows up when you trace the real system]

- [What happens when a bike runs out of battery mid-ride?]
- [What's different in Berlin vs. Austin vs. Paris?]
- [What happens in winter? In events? In construction zones?]

## What you'll discover building this

The process of mapping the system forces you to:
→ Find the documentation that's scattered everywhere
→ Figure out how things actually work (vs. how you assumed)
→ Write down processes nobody documented yet
→ Find the gaps between how the system works and
  how the physical world works

## What this enables

Once you have this, it becomes a shared resource:
→ Agents can navigate Lime's system (not just generic UX)
→ New designers onboard in hours, not weeks
→ Developers see second-order impacts from the physical world
→ UX sees second-order impacts from system changes
→ Training manuals that stay current
→ Link mermaid states to Figma screens —
  navigable by humans and agents

File 5: skills/design-critique.md

A structured AI workflow for one specific task. This tells AI exactly how to review a design the way your team would — not with generic heuristics, but with your principles, your constraints, your edge cases.

# Design Critique

## When to use this
When you want structured feedback on a screen, flow,
or interaction from Lime's perspective.

## What you give it
- The design (screenshot, description, or flow)
- Which area: rider / supply / ops
- What stage: exploring / refining / handing off

## How it should work

1. Read TASTE.md first. That's the lens.

2. Load the right context file (rider.md or supply-ops.md).

3. Look at the design through these questions:

   CLARITY
   Can someone figure out what to do without thinking?
   Remember: they might be outside, in the rain,
   on a small screen, distracted.

   CONSISTENCY
   Does this follow the design system?
   Does it match how similar things work elsewhere?

   EDGE CASES
   What happens when connectivity drops mid-flow?
   When the user is in a market with different rules?
   When data is missing or unexpected?
   When someone makes a mistake?

   ACCESSIBILITY
   Different abilities. Different light conditions.
   One hand. Moving vehicle.

   DOES THIS FEEL LIKE LIME?
   Reference specific things from TASTE.md.
   Flag anything that feels like it could be
   any company's design.

4. For each issue:
   - What's wrong
   - Which principle it goes against
   - A direction to consider (not a solution —
     the designer decides the solution)

5. Flag anything that needs a human call:
   "This is a judgment call — here's the tension..."

## What the output should look like

SUMMARY: One paragraph overall take.

ISSUES: Bulleted, severity order.
  Each one: what → why → direction.

NEEDS A HUMAN EYE: Things that require taste
  or empathy, not just heuristic checking.

WHAT'S WORKING: Be specific about what's good.
  Say why.

## What this doesn't do
- Make final design decisions
- Choose between two valid options
- Judge whether a feature is worth building
- Replace design review with actual humans

Getting started

Monday: Fill in TASTE.md. Don't overthink it — messy and specific is better than polished and generic. The weird stuff that only your team knows is the most valuable part.

This week: Try design-critique.md on a real project. Paste TASTE.md + the skill into Claude or ChatGPT, share a screenshot, and see what comes back. Compare it to what you'd get without the taste doc.

This month: Fill in one context file — whichever side your team works in more. Add real quotes from research. Add the weird rules. Add past decisions and why. The more specific the context, the more useful the output.

Ongoing: When AI does something good, note why. When it misses, figure out what was missing and add it. These docs get better with use — that's the whole point.

Where this goes

Now:       Markdown files you paste into conversations
           One person curates, team benefits

Weeks:     Shared repo or folder
           Team contributes — more context, more skills
           (onboarding, edge cases, Jira specs...)

Months:    Connected to your tools automatically
           AI reads your team's context before every interaction
           No more copy-paste — it just knows

That last step is where tools like Smaak or MCP connections come in. But the first two steps are just writing things down and sharing them. No infrastructure needed.