> For the complete documentation index, see [llms.txt](https://t420.gitbook.io/t420/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://t420.gitbook.io/t420/claude-master-polish-10of10.md).

# claude-master-polish-10of10

## FleetOS Master 10/10 Polish Task List

Paste this into a fresh Claude Code terminal session at the FleetOS repo root.

***

You are working in the `ZBO19/FleetOS` repository.

Read these first:

1. `docs/agent.md`
2. `docs/production-plan.md`
3. `docs/api-mcp-spec.md`
4. `docs/openapi.yaml`
5. `docs/claude-final-10of10-kickoff.md`
6. `docs/claude-screenshot-ui-punchlist.md`

Then inspect the actual code, the landing experience, the docs, the settings pages, the dashboard flows, and the mobile screenshots before making any claims.

### Mission

Push FleetOS to **10/10 product quality**, **10/10 UX/UI**, and **10/10 developer-platform credibility**.

This is not a narrow bugfix task. This is a full-system polish and hardening pass across:

* product UX
* mobile UI
* dashboard flows
* settings/admin surfaces
* marketing site
* documentation
* developer docs
* API platform discoverability
* terminology
* contrast/readability
* trust and polish

Do not stop at one category. Do not stop after backend hardening. Do not stop after mobile polish. The goal is that the product, the code, the docs, and the marketing all feel like one coherent, premium, production-grade platform.

***

### Non-negotiables

* Do not break the core supplier ↔ fleet workflow.
* Do not break the API.
* Do not leave docs claiming things that the UI or implementation do not support.
* Do not redesign the brand.
* Keep the current FleetOS visual language.
* Improve clarity, hierarchy, spacing, ergonomics, trust, and discoverability.
* Keep changes incremental and strongly typed.
* Make the mobile experience feel intentional, not desktop compressed into a phone.
* Make the developer experience feel like a first-class product surface.

***

## Part 1 — Core UX/UI issues to fix everywhere

### 1. Raise contrast and readability across the whole product

There are still too many places where text is technically visible but not comfortably readable.

#### Fix globally

* raise contrast for secondary labels
* raise contrast for section headers
* raise contrast for empty-state/status text
* raise contrast for placeholders and helper text where they are currently muddy
* keep primary values strongest, but do not let secondary text disappear

#### Specific problem examples

* `No photos attached`
* `DETAILS`
* `COORDINATOR`
* `SCHEDULE`
* `BAY`
* `TECH`
* `VEHICLE`
* `PARTS`
* `Send Response`
* marketing body copy in feature cards
* settings explanatory copy
* docs/support/footer link text

#### Target

* primary values: strong near-white
* secondary labels: readable soft off-white / brighter slate
* helper text: still subordinate, but clearly readable

***

### 2. Strengthen affordances on low-emphasis controls

Some controls still feel too faint or too passive.

#### Fix

* strengthen borders for ghost/outline controls where needed
* make inactive-but-important states feel intentional, not washed out
* make action containers feel obviously interactive when they are interactive

#### Specific examples

* vehicle `Pending` state box
* `+ Add Part` button
* some outline buttons in cards
* subtle card CTAs that are too low-emphasis

#### Target

* a user should know instantly what is clickable, what is a status, and what is disabled

***

### 3. Reduce floating action interference

The floating feedback/chat button and floating add-job button still compete with content.

#### Fix

* reduce FAB size slightly if still too dominant
* reduce glow/shadow intensity
* improve safe-area positioning
* prevent overlap with card CTAs and form controls
* ensure feedback/chat button does not sit on top of critical interaction zones
* ensure add-job button feels useful, not loud

#### Target

* floating actions should be easy to find but should not visually interrupt reading or tapping

***

## Part 2 — Mobile-first dashboard polish

### 4. Make job cards feel premium on mobile

#### Fix collapsed cards

* tighten label/value spacing
* reduce text heaviness where still too dense
* improve truncation treatment for long fleet/supplier/location strings
* make card CTA anchor (`Respond`, `View Details`, `Review Quote`) feel cleaner and more intentional
* ensure badge, WO number, and urgency pill align cleanly

#### Fix expanded cards

* maintain clearer section rhythm
* keep sections readable and scannable
* reduce visual fatigue from too many lines/blocks
* ensure every expanded section has a clear purpose

#### Target

Collapsed cards should scan in under 2 seconds. Expanded cards should feel organized, not exhausting.

***

### 5. Finalize schedule block ergonomics

The schedule layout is much better, but it still needs to feel absolutely first-class.

#### Fix

* ensure section heading contrast is strong enough
* keep Bay / Tech / Vehicle / Parts rows visually balanced
* ensure selects are visually consistent in width and height
* ensure `Pending` state is readable and state-like, not placeholder-like
* ensure `+ Add Part` feels like a clear secondary action
* ensure spacing between rows remains calm and premium
* check mobile keyboard behavior when adding parts
* check tap feedback and focus states

#### Target

This section should feel like a real operations panel, not a styled form fragment.

***

### 6. Clean the response section

#### Fix

* keep it compact and action-oriented
* do not repeat information already shown in the header if not needed
* keep helper text concise
* ensure input placeholders are readable
* ensure Send Response is clearly primary
* ensure Decline is clearly secondary
* ensure Request Vehicle Delivery is tertiary/contextual where appropriate
* refine spacing between note, amount row, attachment row, CTA row, and secondary actions

#### Important rule

Do not visually re-introduce repeated budget emphasis if budget is already shown in the card header.

***

### 7. Improve fleet-side expanded cards too

Supplier-side screens have gotten most of the attention. Fleet-side expanded cards still need equal polish.

#### Fix

* ensure quote review screens feel just as intentional as supplier response screens
* improve photo-add state on fleet-side expanded jobs
* improve Contact / Cancel Job row spacing and emphasis
* ensure Ready for Pickup and completion evidence sections feel premium and easy to parse

***

## Part 3 — Add Job modal and form system polish

### 8. Make Add Job modal feel production-grade

This is one of the most important creation flows in the app.

#### Fix

* improve label contrast
* improve placeholder readability
* tighten section rhythm
* ensure field spacing is consistent
* refine segmented control styling for `Existing Fleet` / `New Fleet`
* ensure priority pills feel deliberate and accessible
* improve mobile modal scroll rhythm
* improve more-options block discoverability
* improve date picker and icon alignment
* ensure close control is easy to hit and visually balanced

#### Target

The Add Job flow should feel premium and low-friction on both mobile and desktop.

***

### 9. Standardize form system behavior everywhere

#### Fix

* input height consistency
* border radius consistency
* label spacing consistency
* placeholder color consistency
* focus ring / focus border consistency
* inline helper text consistency
* error state consistency
* disabled state consistency
* select arrow/icon alignment consistency

#### Surfaces to audit

* Add Job modal
* feedback modal
* settings forms
* response panels
* docs/settings control panels

***

## Part 4 — Settings / admin / developer control surface

### 10. Turn Settings into a truly polished control surface

The settings page is much better, but still feels like stacked panels rather than a premium admin experience.

#### Fix

* improve section hierarchy
* improve spacing between cards
* improve internal spacing within cards
* improve typography hierarchy inside cards
* reduce dead space where it feels accidental
* ensure Back button/header treatment feels polished
* ensure chat/feedback bubble does not overlap settings controls

#### Target

Settings should feel deliberate, calm, and premium, not merely functional.

***

### 11. Make Developer section feel real, not placeholder-ish

Current screenshots suggest API Keys / Webhooks still feel too thin.

#### Fix

* if self-serve is implemented, expose real metadata and controls beautifully
* if still partial, clearly state current availability and next step
* improve explanatory copy so it reads like a platform feature, not filler
* tighten vertical spacing and card hierarchy
* add trusted cues: one-time visibility for secrets, revoke behavior, delivery status where relevant

#### Target

A developer should believe FleetOS is a serious integration surface.

***

## Part 5 — Marketing site / homepage / messaging

### 12. Upgrade mobile landing page to premium quality

The homepage is much stronger, but still needs final polish.

#### Fix nav/header

* ensure top nav is readable and balanced on mobile
* improve spacing between logo, nav items, and Login CTA
* ensure menu behavior is intentional and premium

#### Fix hero

* tighten headline wrapping and spacing
* ensure subheadline is readable at a glance
* refine CTA spacing and hierarchy
* improve demo CTA clarity
* ensure phone mockup feels proportionate and premium

#### Fix feature sections

* increase body-copy readability in feature cards
* reduce long-block fatigue
* tighten vertical rhythm between sections
* ensure chips/buttons for target segments feel clean and consistent

#### Fix footer

* raise footer link readability
* improve spacing and grouping
* ensure support/recovery links are easy to read and tap

#### Target

The landing experience should look like a premium SaaS/product company, not an impressive prototype.

***

### 13. Tighten marketing copy throughout

#### Fix

* remove any remaining awkward or overlong sections
* ensure copy is direct, operational, and believable
* avoid bloated paragraphs on mobile
* ensure every major section clearly answers one question:
  * what is FleetOS?
  * who is it for?
  * why does it matter?
  * why trust it?
  * how do I start?

#### Specific attention areas

* hero copy
* category/segment sections
* benefit cards
* compliance section
* testimonial/problem-solution sections
* developer/platform framing

#### Target

Concise, credible, operational, and premium.

***

## Part 6 — Documentation and developer docs

### 14. Make docs as polished as the product

#### Fix

* improve mobile readability of docs pages
* improve section hierarchy
* improve code-block readability and overflow behavior
* improve spacing between sections
* improve CTA/button treatment
* improve cross-linking between product docs and API docs

#### Target

Docs should feel like part of the product, not an afterthought.

***

### 15. Audit every docs claim against reality

#### Fix

* verify product docs against UI
* verify API docs against actual handler behavior
* verify settings/developer docs against actual control surfaces
* remove or caveat anything still ahead of implementation

#### Target

No broken promises. No fake maturity.

***

### 16. Improve API docs trust signals

#### Fix

* expose OpenAPI link/download if possible
* explain auth clearly
* explain webhook behavior clearly
* explain self-serve vs managed behavior clearly
* improve environment/version language
* tighten examples and wording

#### Target

A real engineer should trust the API docs without guessing.

***

## Part 7 — Product consistency / terminology / information architecture

### 17. Standardize terminology across the whole app

#### Audit and unify

* work order
* request n- job
* supplier
* fleet
* client
* partner
* quote
* approval
* ready for pickup
* in progress / in shop / pending approval

#### Rule

Pick canonical user-facing terms and use them consistently across:

* dashboard cards
* expanded views
* settings
* docs
* homepage
* API docs

#### Target

No terminology drift that makes the product feel stitched together.

***

### 18. Standardize visual hierarchy tokens

#### Fix globally

* heading sizes
* section title sizes
* secondary label colors
* helper text color
* ghost button treatment
* card border strength
* divider opacity
* shadow/glow behavior
* badge treatment
* spacing scales

#### Target

A user should feel the same visual logic across dashboard, settings, modals, docs, and homepage.

***

## Part 8 — Accessibility, usability, and best-practice polish

### 19. Accessibility pass

#### Fix

* text contrast everywhere
* tap targets on mobile
* focus visibility on all controls
* aria labels on floating buttons, close buttons, key actions
* keyboard navigation where relevant
* semantic heading order in marketing/docs screens
* enough distinction between placeholder text and entered text

#### Target

Meet strong practical accessibility, not just aesthetics.

***

### 20. Error / empty / pending states pass

#### Fix

* empty-state readability
* upload state readability
* loading skeleton consistency
* mutation error banners clarity
* success overlays/messages polish
* no dead-looking controls when waiting

#### Target

The app should feel alive and intentional even in edge states.

***

### 21. Performance / polish pass on mobile

#### Fix

* reduce unnecessary visual clutter
* avoid oversized shadows/glows on mobile
* ensure scroll feels clean in modals and expanded cards
* ensure no overlay collisions
* ensure safe-area spacing is respected
* ensure floating controls do not block interactive content

***

## Part 9 — API / security / architecture final pass

### 22. Keep the API platform credible and secure

#### Verify and polish

* no sensitive fields leaked through client-readable paths
* API keys / webhooks self-serve story is either fully real or honestly constrained
* developer settings cards feel complete
* API docs and implementation remain aligned

***

### 23. Keep shadow layer optional and clean

#### Verify and polish

* no fragile hard dependency from core workflow into shadow tracking if avoidable
* structured logging instead of silent swallow patterns
* instrumentation remains additive

***

### 24. Preserve architecture quality while polishing

#### Rule

Do not hack the UI polish into giant messy components. Refactor cleanly where needed. Keep code maintainable.

***

## Part 10 — Screenshot-specific issues to address immediately

### Dashboard / cards

* make small labels brighter
* make `No photos attached` readable
* make `Pending` in vehicle row clearly visible
* strengthen `+ Add Part` affordance
* reduce floating button interference
* keep card CTA anchors clean

### Feedback modal

* improve label contrast
* improve placeholder readability
* ensure it feels consistent with Add Job modal
* ensure primary/secondary button balance is strong

### Add Job modal

* improve label contrast
* improve placeholder contrast
* refine more-options block treatment
* ensure modal feels premium and not overly tall/heavy

### Settings

* improve developer card substance and hierarchy
* improve spacing in notifications and developer sections
* ensure chat button does not overlap controls

### Homepage / marketing

* improve body-copy readability in feature sections
* improve chip/button spacing and rhythm
* improve footer link readability
* keep hero and support/recovery sections sharp and readable

***

## Execution order

### Phase 1 — Readability and contrast

Fix all weak text contrast, low-emphasis controls, and ghost states first.

### Phase 2 — Floating controls and mobile polish

Fix overlapping/interfering floating actions and remaining mobile ergonomics issues.

### Phase 3 — Settings, modals, and docs polish

Upgrade admin/settings/forms/docs so they match the dashboard quality.

### Phase 4 — Homepage / marketing pass

Tighten readability, trust, and premium feel on the landing site.

### Phase 5 — Terminology / consistency / cleanup

Do the final sweep for consistency across the whole product.

### Phase 6 — Verification

Run through the main supplier flow, fleet flow, settings flow, docs flow, and homepage flow on mobile and desktop.

***

## Required output style while working

* Be concrete.
* Show exact files changed.
* Keep a running checklist.
* Make incremental commits.
* Call out visual-token changes explicitly.
* Call out any doc/product mismatches explicitly.
* Keep the product truthful while improving it.

***

## First response format

Your first response must contain exactly these sections:

1. `Global polish gaps`
2. `Highest-priority UI/UX fixes`
3. `Marketing/docs gaps`
4. `Architecture/API constraints to preserve`
5. `Execution plan`
6. `First files I will change`

Then start work.

***

## Definition of done

You are done only when FleetOS feels 10/10 in all of these:

* supplier dashboard
* fleet dashboard
* mobile readability
* add-job flow
* settings/admin flow
* homepage/marketing site
* docs / developer docs
* product trust / terminology / consistency

The standard is: premium, coherent, readable, credible, and production-minded.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://t420.gitbook.io/t420/claude-master-polish-10of10.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.