# SKILLS — Designing Collect! applications
A practical handbook for designers and developers shipping product UI that
"feels like Collect!". Read once, refer back when you're stuck.
If you're an AI assistant (Claude Code, Cursor, Copilot Chat), read
[`CLAUDE.md`](CLAUDE.md) first — it's shorter and more prescriptive.
---
## 1. The mental model
Collect! is **receivables management software**. The brand promise is
**Trustworthiness · Reliability · Flexibility · Value**, expressed through a
single character trait: **Competence** — reliable, intelligent, successful.
What that means in practice:
- The interface should feel **calm, dense, professional** — not playful, not
trendy, not minimalist-to-the-point-of-empty.
- We use **clear visual hierarchy** (Persian Blue headings, Mid Grey body)
rather than decorative ornamentation.
- We reserve colour for **meaning**, not mood. Orange means *do this*. Teal
means *brand, link, focus*. Green means *paid*. Berry means *informational*.
## 2. Token-first
Every visual value comes from `css/tokens.css`. The four token families:
| Family | Tokens | Use for |
|---|---|---|
| Colour | `--color-primary`, `--color-accent`, `--color-text`, … | All paint |
| Type | `--font-heading`, `--font-body`, `--fs-12 … --fs-60`, `--leading-*` | All text |
| Space | `--space-1 … --space-24` (4 px base) | All padding & margin |
| Surface | `--radius-*`, `--shadow-*`, `--duration-*` | Corners, elevation, motion |
If you find yourself writing `color: #2BA3BB` or `padding: 13px`, stop —
there's a token for it.
## 3. Component catalogue
The full catalogue is `index.html`. The most-used pieces:
- **Buttons** — `.btn` with one of `.btn-primary | .btn-accent | .btn-secondary | .btn-outline | .btn-ghost`. Size: `.btn-sm | (default) | .btn-lg`. Always pill-shaped.
- **Badges** — `.badge` + intent (`-primary | -accent | -success | -info | -neutral`). Add `.badge-dot` for a status dot.
- **Cards** — `.card` is the base; add `.card-feature | .card-accent | .card-info | .card-success` for a coloured top stripe, or `.card-stat` for KPI numbers.
- **Alerts** — `.alert.alert-info | .alert-success | .alert-warning | .alert-danger`. Pair with an icon from the sprite.
- **Forms** — wrap each control in `.field` with a `.field-label`. `.input | .textarea | .select` share the same border + focus ring. Use `.checkbox` / `.radio` containers; native input shows `accent-color: var(--color-primary)`.
- **Tables** — `.table`. Header row is `--color-bg-alt`, body rows hover-tint. Keep rows on a 14 px type scale.
- **Tabs** — `.tabs > .tab[aria-selected]`. Underline is the active indicator.
- **Progress** — `.progress > span` with inline `width: NN%`.
- **Avatar** — `.avatar` (initials, 40 px) or `.avatar-lg` (64 px).
## 4. Layout rules of thumb
- **Container width:** `var(--container-max)` = 1180 px. Don't go wider for
text content.
- **Reading measure:** `var(--content-max)` = 72ch. Body paragraphs already
cap at this — don't override.
- **Spacing rhythm:** vertical rhythm uses `--space-4 (16 px)` between
related blocks, `--space-8 (32 px)` between sub-sections, `--space-10
(40 px)` or more between top-level sections.
- **Don't centre body text.** Left-align everything except hero callouts and
empty states.
## 5. Iconography
- 24 × 24 grid, 1.8 stroke, rounded caps and joins.
- Stored as a single SVG sprite: `assets/icons/icons.svg`.
- Embed via:
```html
```
- Colour inherits from `currentColor` — change the parent's `color`, not the
SVG. If you need a coloured icon background, use the `.card-icon` pattern
(44 × 44 tinted square, rounded-md).
- Need a new icon? Add a `` to the sprite, match stroke +
cap conventions, ship it in the same PR that uses it.
## 6. Imagery & illustration
- **Product screenshots** — show real Collect! UI, no faked data that
contradicts what the product actually does. Crop to remove window chrome.
- **Photography** — if used, lean on muted blues / greys. Avoid stock photos
of generic "business handshakes."
- **Don't** invent illustration styles unilaterally. If we need illustration,
open a discussion first — it expands the brand and needs sign-off.
## 7. Voice — applied
The 2019 guide says: *clear and succinct, active voice, no computerese*. In
product UI that translates to:
- **Buttons** — verb-first, no trailing "…". "Save changes", "Send notice",
"Export CSV". Not "Click here to save".
- **Empty states** — name the thing, then offer one action. "No payments yet.
Import a file or add one manually."
- **Errors** — say what went wrong and what to do next. Avoid "An error
occurred."
- **Help text** — under 80 characters. If you need more, link to docs.
## 8. Accessibility checklist (every PR)
- [ ] Every interactive element has a visible `:focus-visible` state.
- [ ] Colour is not the *only* way information is conveyed (pair with text,
icon, or pattern).
- [ ] Body text contrast ≥ 4.5:1; large text ≥ 3:1.
- [ ] All form controls have a programmatic label.
- [ ] Decorative icons use `aria-hidden="true"`; meaningful icons have a
label or adjacent text.
- [ ] Keyboard tab order matches visual order.
## 9. Versioning & PR hygiene
When you change any CSS in `css/`:
1. Bump the `Version:` line at the top of the file (semver: patch / minor /
major).
2. If you changed token semantics, update both `README.md` and `CLAUDE.md`.
3. Demonstrate any new component or variant in `index.html`. The showcase is
not optional documentation — it's the contract.
## 10. Where things live
| You want to… | File |
|---|---|
| Change a brand colour or font | `css/tokens.css` (probably don't) |
| Add a new component | `css/components.css` + a section in `index.html` |
| Tweak typography rules | `css/base.css` |
| Add or replace a logo | `assets/logos/` + originals live in the parent repo under `docs/ComtechSystems_CorporateIdentity2019/logos/` |
| Add an icon | `assets/icons/icons.svg` (new ``) |
| Read the brand voice / colour philosophy | `docs/corporate_identity_2019.md` |
| Read what changed for 2026 | `docs/corporate_identity_2026.md` |