Skip to content
Skills Library
Design & UX · Analysis

optical-alignment-ui

/optical-alignment-ui

Optical alignment and optical adjustment for digital UI (precision vs perception). Use when icons look off-center, play buttons lean left, circles look smaller than squares, icon sets feel uneven, icon+label pairs misalign, ALL CAPS looks oversized, button labels sit wrong, or type needs overshoot / optical margin / font-optical-sizing. Apply evidence-based diagnosis, geometric vs perceptual centers, smallest effective correction, and design-system hand-off. Do not invent universal +2px rules, reduce touch targets, or treat centroid as absolute optical truth.

Licence
CC-BY-4.0
Last repository change
10.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
11
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.

Licence

CC-BY-4.0, otwarta.

What it does and when to use it

Optical alignment and optical adjustment for digital UI (precision vs perception). Use when icons look off-center, play buttons lean left, circles look smaller than squares, icon sets feel uneven, icon+label pairs misalign, ALL CAPS looks oversized, button labels sit wrong, or type needs overshoot / optical margin / font-optical-sizing. Apply evidence-based diagnosis, geometric vs perceptual centers, smallest effective correction, and design-system hand-off. Do not invent universal +2px rules, reduce touch targets, or treat centroid as absolute optical truth.

Original author description

Optical alignment and optical adjustment for digital UI (precision vs perception). Use when icons look off-center, play buttons lean left, circles look smaller than squares, icon sets feel uneven, icon+label pairs misalign, ALL CAPS looks oversized, button labels sit wrong, or type needs overshoot / optical margin / font-optical-sizing. Apply evidence-based diagnosis, geometric vs perceptual centers, smallest effective correction, and design-system hand-off. Do not invent universal +2px rules, reduce touch targets, or treat centroid as absolute optical truth.

How it works

  1. Compatible agents
  2. Companion skill
  3. Scope and rigor
  4. Outcomes (mandatory)
  5. Severity and confidence (independent)
  6. Evidence-Based Optical Workflow
  7. Geometric decision matrix (summary)
  8. Reasoning rules
  9. When to activate / when not
  10. Analysis output format
Original SKILL.md headings · 104 lines, 509 words
SKILL.md preview
---
name: optical-alignment-ui
description: >
  Optical alignment and optical adjustment for digital UI (precision vs perception).
  Use when icons look off-center, play buttons lean left, circles look smaller than
  squares, icon sets feel uneven, icon+label pairs misalign, ALL CAPS looks oversized,
  button labels sit wrong, or type needs overshoot / optical margin / font-optical-sizing.
  Apply evidence-based diagnosis, geometric vs perceptual centers, smallest effective
  correction, and design-system hand-off. Do not invent universal +2px rules, reduce
  touch targets, or treat centroid as absolute optical truth.
metadata:
  author: vinimrdi
  version: "1.5.3"
  language: en
  tags: optical-alignment, optical-adjustment, optical-centering, ui, ux, typography, icons, agent-skills, claude-code, cursor, lovable, pixel-perfect, visual-balance
---

# Optical Alignment UI — Precision vs Perception

**Agent skill** for making digital interfaces *look* balanced when mathematical alignment does not.

Invoke as `/optical-alignment-ui` where supported, or attach this folder as context. Progressive disclosure: load [references/](references/) only when needed. Examples: [examples/](../../examples/). Tools: [scripts/](../../scripts/).

## Compatible agents

See [docs/compatibility-and-integrations.md](../../docs/compatibility-and-integrations.md).

## Companion skill

**[ux-laws-principles](https://github.com/vinimrdi/ux-laws-principles)** — task first; optical craft second.

## Scope and rigor

| Kind | Examples |
|------|----------|
| **Heuristic / practice** | Play-icon nudge, caps size, icon+label |
| **Platform guidance** | Keylines; platform icon notes |
| **Type mechanics** | Overshoot, optical margin |
| **Engineering aid** | Area scale, geometric/alpha centroid — **diagnostic only** |

Optional measurement (diagnostic, not perceptual law):

```bash
pip install -r scripts/requirements.txt

# Raster with alpha
python scripts/centroid.py path/to/icon.png --verbose

# SVG at real UI size (needs cairo system libs for cairosvg)
python scripts/svg_centroid.py path/to/icon.svg --size 24 -v

# Smoke fixtures
python scripts/centroid.py fixtures/play-24.png --json
python scripts/svg_centroid.py fixtures/play.svg --size 24 --json
```

Prefer smallest effective correction. No universal pixel offsets. Re-check contrast and targets after changes.

## Outcomes (mandatory)

| Outcome | When |
|---------|------|
| **Implement** | Evidence sufficient, low risk, a11y safe |
| **Propose** | Plausible; needs human judgment |
| **Abstain** | No imbalance, weak evidence, or wrong skill |

## Severity and confidence (independent)

**Severity** 0–4 · **Confidence** High / Medium / Low / Unverified  
*Severity 3 + Confidence Low* → do not implement yet.

## Evidence-Based Optical Workflow

1. Context capture  
2. Baseline at native size  
3. Geometric analysis (box / centroid / alpha — optional `centroid.py` or `svg_centroid.py`)  
4. Perceptual assessment  
5. Diagnosis (intent, severity, confidence)  
6. Minimal intervention (prefer pad-in-asset)  
7. Visual validation  
8. Design-system hand-off  

Details: [evidence-and-validation.md](references/evidence-and-validation.md) · [geometry-and-centroids.md](references/geometry-and-centroids.md) · [accessibility-and-constraints.md](references/accessibility-and-constraints.md) · [anti-patterns.md](references/anti-patterns.md)

## Geometric decision matrix (summary)

| Problem | Prefer first |
|---------|--------------|
| Symmetric filled rect | Bounding-box center |
| Filled play triangle | Centroid check + eye + pad-in-asset |
| Outline icons | Stroke mass; not fill centroid alone |
| Soft/raster edges | `centroid.py` / alpha weights |
| SVG icons | `svg_centroid.py --size <ui-px>` |
| Circle vs square size | **Name intent** |
| Uneven icon set | Keylines + set review |
| Bad viewBox | Fix asset first |

## Reasoning rules

Visible imbalance first · Grid first · Shift against weight · Color last · Do not fight type overshoot · No one-offset for whole sets · Check anti-patterns · Explain while applying

## When to activate / when not

**Activate:** off-center glyphs, asymmetric icons, circle/square scale, icon+label, uneven sets, caps, overshoot/`opsz`, AI UI optically wrong, asset hand-off.

**Skip as primary:** a11y-only; no composition; illustration-only; universal +2px; physical optics.

## Analysis output format

What observed · Evidence · Concept · What/Why/Who/Where/When/How · Intent · Impact · Severity · Confidence · **Outcome** · Trade-off · Validation · Hand-off

## Reference library

- [Evidence](references/evidence-and-validation.md) · [Geometry](references/geometry-and-centroids.md) · [A11y](references/accessibility-and-constraints.md)  
- [Anti-patterns](references/anti-patterns.md) · [Platform](references/platform-behavior.md)  
- [Typography](references/typography.md) · [Shapes](references/shapes-and-icons.md) · [Color](references/color-and-components.md) · [Implementation](references/implementation.md)  
- [Formulas & sources](references/formulas-limits-sources.md) · [Examples](../../examples/) · [Scripts](../../scripts/) · [Fixtures](../../fixtures/)  

Version: [CHANGELOG.md](../../CHANGELOG.md) (**1.5.3**).
Files in this package (11)
  • SKILL.md 5 KB
  • references/accessibility-and-constraints.md 2 KB
  • references/anti-patterns.md 2 KB
  • references/color-and-components.md 1 KB
  • references/evidence-and-validation.md 2 KB
  • references/formulas-limits-sources.md 3 KB
  • references/geometry-and-centroids.md 3 KB
  • references/implementation.md 1 KB
  • references/platform-behavior.md 2 KB
  • references/shapes-and-icons.md 2 KB
  • references/typography.md 3 KB

Versions

The database has no other skills named optical-alignment-ui.

Database snapshot: 13.11.2026 · package version 50251eeee5d6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100optical-centering
    Use when building or reviewing UI rows that mix text with icons, badges, or uppercase labels, when a user reports text sitting off-center or icons hanging low against labels, or before shipping any chip, menu item, button, table header strip, or badge row. Covers measuring true…
  • 100icon-design
    Design and implement consistent SVG icon systems for UI: keyline grids, stroke rules, optical corrections, outline/filled/duotone styles, icon+text alignment, animation, and accessible markup. Use for UI icons in code; for a logo mark use brand-identity, for illustrations use…
  • 95better-ui
    Applies exact UI polish values: concentric border radius, optical alignment, layered surface shadows, neutral image outlines, a 0.96 press scale, icon cross-fades, and theme-switch transition suppression. Activates when editing component CSS or Tailwind, when an interface looks…
  • 100ui
    Design engineering principles for making interfaces feel polished. Use when building UI, reviewing frontend code, or working on any visual detail, from animations, hover states, shadows, borders, and typography to optical alignment and tabular numbers.
  • 100better-ui
    Design engineering principles for making interfaces feel polished. Use when building UI components, reviewing frontend code, implementing animations, hover states, shadows, borders, micro-interactions, enter/exit animations, choosing or reviewing icons, or any visual detail…
  • 100make-interfaces-feel-better
    UI polish skill — 16 design engineering principles for making interfaces feel polished and professional. Covers typography, surfaces, animations, and performance. Triggers on UI review, design details, "make it feel better", "feels off", 界面打磨, UI细节, border radius, shadows,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.