bikeindex/bike_index / .claude/skills/use-existing-markup
use-existing-markup
VerifiedConvert a branch's hand-written markup to the components that already render it. Covers marketing and landing pages on `SharedBlocks::Marketing` and the donate form, `UI::*` and `Atoms::*` everywhere else, icons and images the repo already has, buttons snapped to existing colors, shadows, and hover states to report. Trigger when a branch adds or redesigns a page's markup, especially a marketing, landing, donate or "how it works" page or a design handoff built from a mockup. Also trigger on "use existing components", "reuse the markup", "is this hand-rolled", and from the `pr` skill's markup audit. It replaces without asking.
Use existing markup
Who runs this
From a session with history, hand this skill to a subagent the way AGENTS.md's Who runs this describes. Use no model override, because matching markup to a component is judgment. Brief it with the base branch, what the page is for, and any design choices the user already made. It replies with the four lists under The reply, with the conversions left uncommitted in the working tree.
Find what the branch adds
rtk proxy git diff origin/main...HEAD -U0 -- '*.erb' '*.haml' 'app/components/*.rb' |
grep -E '^(\+\+\+ |\+\s*%[a-z]|\+.*(<[a-z]|link_to|button_to|content_tag|tag\.|tw:|inline_svg_tag|image_tag))'
rtk proxy git diff origin/main...HEAD --name-only --diff-filter=A -- app/assets/images app/components
Nearly every template line matches tw:, so treat the output as a map of where to read. Read the templates whole.
Undo what the branch added to a shared component
A page that already renders the right component can still have bent it to fit the mockup. Diff the shared components themselves:
rtk proxy git diff origin/main...HEAD -- app/components/ui app/components/atoms app/components/shared_blocks
Every keyword argument, variant or style map the branch added there is a mockup override. Revert that component and its spec to origin/main and render the default at the call site, without asking. Don't tidy the new variant up or move its classes around. That keeps it, and a variant added for one caller stays for every caller. #4678 added boxed: to UI::Accordion so one FAQ matched its mock, while every other FAQ on the site renders the default rows.
The exception is an argument the user asked for in this conversation.
The same override can sit outside the component. A wrapper whose classes restyle what renders inside it is a variant by another route: <span class="tw:uppercase tw:tracking-wider"> around a UI::Badge or a [&_a]: selector on a button's parent. Strip those classes and keep only the wrapper's layout (margin, display, grid placement). Drop the wrapper if layout was all it carried.
Replace, don't ask
Convert every hand-written piece an existing component covers, without asking first. Then name each visible change in your reply.
Snap to the nearest existing variant rather than overriding one. A button the mockup colored or sized by hand becomes the closest UI::Button / UI::ButtonLink color: and size:, with the override classes deleted. Don't write html_class: "tw:bg-[#…]! tw:px-8!" to keep the mockup's look. A badge gets the nearest UI::Badge color:, and a card the nearest UI::Card shadow:. Never add a UI::* argument to keep a mockup's exact look. The nearest variant is the answer.
! is for layout only (width, padding, grid placement), on a class that the component's own class outranks. Pages::RecoveryStories::Index puts tw:p-7! on UI::Card.
Marketing pages: SharedBlocks::Marketing
A marketing page is a for_* landing page, or the donate, recovery stories, e-bike rules, marketplace "how it works" or register landing page, or one like them. It goes together from this kit, not from ui/ alone. A design handoff draws these blocks by hand, so its mock is no sign they're missing:
| Hand-written | Use |
|---|---|
The page root (tw:-mt-(--nav-gap) tw:-mb-(--footer-gap) tw:bg-white …) and its font <link> | SharedBlocks::Marketing::Wrapper, rendered from the controller (render SharedBlocks::Marketing::Wrapper::Component.new(page: …)) |
A section's content width (tw:mx-auto tw:max-w-6xl tw:px-…) | SharedBlocks::Marketing::Wrapper::Component::CONTAINER_CLASSES |
An h2 with an eyebrow or intro paragraph | SharedBlocks::Marketing::SectionHeading (eyebrow:, eyebrow_color:, intro:) |
| An eyebrow on its own | SharedBlocks::Marketing::SectionHeading::Component.eyebrow_classes(color) |
| An icon in a colored circle beside a title and body | SharedBlocks::Marketing::IconFeature (card: true for the bordered tile) |
| Bikes registered, recoveries, value returned, partners | SharedBlocks::Marketing::RegistryStats. It reads Counts itself, so the controller passes nothing |
| Other figure/label blocks | SharedBlocks::Marketing::NumberBlocks |
| A colored band with a heading and a button | SharedBlocks::Marketing::CallToActionBanner |
| A gradient two-column band | SharedBlocks::Marketing::InvertedBlock |
| A strip of recovery stories | SharedBlocks::Marketing::RecoveryStories |
| Any donation or membership form | Pages::Donate::Form in a UI::Card, the way Pages::RecoveryStories::Index embeds it, with its own referral_source: |
| An FAQ | UI::Accordion |
Pages::Register::Views::Landing is the worked example. Its hand-rolled $5/$15/$50 donation form and a stats strip that took four counts from the controller both became the components above.
Everywhere else: UI::* and Atoms::*
Read app/components/ui/ and app/components/atoms/, plus the sibling pages/ and shared_blocks/ components that render the same thing. Convert:
- cards to
UI::Card - headings to
UI::Header - link rows to
UI::ButtonGroup - pills to
UI::Badge - a
link_to … method:toUI::ButtonLink
A class map that repeats another component's moves to something both of them already render.
Icons: use the file that's already there
Check every icon the branch adds or newly references. For each one, ask whether the repo already has it, and if so, use the existing file and delete the added one. Look in:
- all of
app/assets/images/(not justicons/), including thelucide-*copies another redesign brought in app/javascript/bikebook/templates/icons.js- text glyphs in templates
Check two ways:
# The same drawing under another name
d=$(grep -o 'd="[^"]*"' app/assets/images/icons/<new>.svg | head -1); grep -rlF -- "$d" app
# The same subject under another name
ls app/assets/images/icons | grep -iE '<subject>|<synonym>'
On the register landing page, store.svg was a second Lucide store icon beside main's lucide-store.svg. A trailing arrow is the text <span aria-hidden="true">→</span> (frontend-conventions has that rule), not an arrow-right.svg.
Images: use the original, never a copy
Check every PNG, JPG, WebP or GIF the branch adds, in any directory, not just the icons. A design handoff's illustrations are already in the repo. The drawn originals are in kelsey_redesign/, and a served one is a byte-identical copy under its original name in app/assets/images/kelsey/illustrations/. A handoff's copy comes resized, re-encoded and renamed, so neither a hash nor the filename matches. Search on the subject words instead, across the whole repo:
git ls-files | grep -iE '<subject>|<synonym>' | grep -iE '\.(png|jpe?g|webp|gif|svg)$'
Then open both files and compare the drawings. For a match:
- Already served (under
app/assets/images/): reference that file. - Only in
kelsey_redesign/: copy it unchanged intoapp/assets/images/kelsey/illustrations/, keeping its original name.
Either way, delete the branch's copy. Never shrink or convert it to WebP to save bytes; pages already serve the originals.
The register landing page had four copies in register_landing/, all resized WebPs. bike-hero.webp was comic-assets_bike-hero.png (already on four pages), and bike-bell.webp was comic-assets_bike-bell.png. u-lock.webp and stolen-alert.webp were comic-assets_u-lock.png and comic-assets_presentation-stolenalert.png, which were only in kelsey_redesign/ until then. A check of icons/ alone missed all four.
Shadows
- Remove small shadows:
tw:shadow-sm,tw:shadow,UI::Cardshadow: :small, or ashadow-[…]with a blur of a few pixels. On a static card a small shadow reads as a hover state (UI::Cardsays so). #4665 dropped them site-wide. - Keep big shadows, but call each one out in your reply:
tw:shadow-mdand up,UI::Cardshadow: :largeor:black, and anydrop-shadow-[…]on an image. The user decides whether each one stays.
Hover states
Call out every hover state on something that isn't a UI::Button or UI::ButtonLink: a hover: utility on a card, tile, row or label, and a group-hover: or has-[:hover] effect. Say what it's on and what it does. Don't remove it. A twlink link's own hover is the standard link style, so leave it out.
The reply
Always report, and lead with the conversions whenever there are any. The user should never find a change to their page that the reply didn't mention.
- Each conversion, and each component argument you reverted, with the visible change it makes.
- Each big shadow kept.
- Each hover state on a non-button.
- Each hand-written piece kept, and what no component covers.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |