feat(skills): six new ms-* skills

ms-archify (evidence-based architectural mapping), ms-sdlc,
ms-proactive-agent, ms-goal, ms-grill-me, ms-frontend-design.
This commit is contained in:
2026-09-07 14:07:16 -05:00
parent 193479b52d
commit 3ea385223e
14 changed files with 1363 additions and 0 deletions
@@ -0,0 +1,34 @@
# Accessibility requirements and checks
Apply these checks to changed surfaces. WCAG 2.2 AA is the default target;
this focused checklist is not a complete conformance assessment. Honor the
actual criterion's scope and exceptions rather than inventing stricter legal
claims. House recommendations are labeled separately.
| ID | Requirement | Verification and qualification |
| --- | --- | --- |
| A11Y-01 | Ordinary text contrast at least 4.5:1; qualifying large text at least 3:1. | Measure actual foreground/background pairs in applicable states. Large text is at least 18pt, or 14pt bold (approximately 24/18.67 CSS px). Account for images/gradients behind text. Respect criterion exceptions; do not round a failing ratio upward. |
| A11Y-02 | Visual information required to identify controls, states, and meaningful graphics meets applicable 3:1 contrast against adjacent colors. | Inspect essential boundaries, indicators, and authored focus cues. Decorative borders and every hover color difference are not automatically subject to this rule. |
| A11Y-03 | Meaning must not depend on color alone. | Pair errors, status, chart distinctions, and selection with text, shape, pattern, or another appropriate cue. |
| A11Y-04 | Pointer targets meet 24 × 24 CSS px or a valid criterion exception. | Measure the hit region, not the icon. For undersized targets using the spacing exception, centered 24px-diameter circles must not intersect another target or another undersized target's circle. Inline text links and other documented exceptions exist. A 44 × 44 target is a house touch recommendation, not the AA minimum. |
| A11Y-05 | All functionality is keyboard operable except genuinely path-dependent input; no keyboard trap. Focus is visible and not entirely hidden by author-created content. | Complete the primary flow with keyboard input and check sticky headers, banners, overlays, order, and visible focus. Prefer fully unobscured focus as a house default. Provide non-drag alternatives when required. |
| A11Y-06 | Semantic structure, accessible names, and appropriate role/state/value. | Prefer links for navigation and buttons for actions. Check landmarks, heading hierarchy, labels, meaningful image alternatives, decorative image treatment, and programmatic errors/status. Do not add ARIA where native semantics suffice. |
| A11Y-07 | Ordinary vertically scrolling content reflows at 320 CSS px without lost information/functionality or two-dimensional page scrolling. | Test narrow width and zoom. Genuine two-dimensional content such as a data table/map may have an appropriately contained scrolling region. Do not conceal required content to pass. Also check text resizing to 200% without loss. |
| A11Y-08 | Content remains usable with WCAG text-spacing overrides. | Apply line height 1.5 times font size, paragraph spacing 2 times, letter spacing 0.12 times, and word spacing 0.16 times where applicable. These are override resilience checks, not required authored typography values. |
| A11Y-09 | Dialogs follow an appropriate accessible interaction pattern. | For a modal: sensible initial focus, Tab/Shift+Tab contained inside, Escape dismissal, accessible name, inert background, and focus restored to the trigger or logical successor. A nonmodal banner should not trap focus. |
| A11Y-10 | Motion does not prevent access; respect reduced motion as a house requirement. | Check reduced-motion behavior; preserve state meaning without movement. Apply relevant pause/stop/hide and flashing criteria to moving or flashing content. |
Sources for exact applicability and exceptions:
- [WCAG 2.2 reference](https://www.w3.org/WAI/WCAG22/quickref/)
- [Text contrast](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
- [Non-text contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html)
- [Target size](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)
- [Focus not obscured](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html)
- [Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html)
- [Text spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html)
- [Modal dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
Automated checks can identify some violations; combine them with actual
keyboard operation, rendered inspection, and assistive-technology checks
appropriate to the change. Record any unavailable checks as not verified.
@@ -0,0 +1,98 @@
# Design principles as operating rules
These are contextual heuristics with concrete checks. The implementations
below are this skill's application of the linked principles. They are not
claims that a psychological law prescribes an exact component or pixel value.
## UX-01 — Familiar behavior (SHOULD)
**Applies:** navigation, controls, and changes to an established interface.
**Behavior:** reuse familiar control semantics, labels, and platform
conventions. Preserve established product patterns unless changing them
solves a demonstrated problem.
**Check:** walk the same task before and after the change; confirm users do
not need to discover a new meaning for an existing control.
**Exception:** a specialized interaction may be justified by the task; provide
discoverable instructions and an accessible alternative where needed.
**Source:** [Jakob's Law](https://lawsofux.com/jakobs-law/).
## UX-02 — Reliable targets (SHOULD)
**Applies:** pointer and touch actions.
**Behavior:** provide generous actual hit areas, separate neighboring actions,
and place frequent actions near their task context. Keep destructive actions
distinct from frequently used actions to reduce accidental activation.
**Check:** inspect hit areas and pointer travel at narrow and wide layouts;
exercise adjacent actions with touch or an appropriate simulation.
**Exception:** dense tools may use smaller controls, subject to the
requirements in [accessibility](accessibility.md); icon size is not hit size.
**Source:** [Fitts's Law](https://lawsofux.com/fittss-law/).
## UX-03 — Manage choices (SHOULD)
**Applies:** menus, forms, onboarding, and decision-heavy screens.
**Behavior:** organize choices by intent; make the next step clear in the
active task region. Disclose infrequent complexity progressively without
hiding frequent actions or information needed for a decision.
**Check:** complete representative tasks; inspect whether grouping or hidden
options create extra search, backtracking, or unnecessary steps.
**Exception:** comparison tasks and expert tools can benefit from simultaneous
options. There is no universal maximum menu length or one-button-per-page rule.
**Source:** [Hick's Law](https://lawsofux.com/hicks-law/).
## UX-04 — Spacing communicates relationships (SHOULD)
**Applies:** forms, content groups, toolbars, and responsive composition.
**Behavior:** use smaller gaps within groups than between groups. Keep labels,
help, errors, and controls together. Use a shared region or border when it
clarifies a real boundary; not every group needs a card.
**Check:** examine grouping after wrapping, at narrow widths, and with long
labels. A field error must not appear to belong to its neighbor.
**Exception:** a stronger semantic or visual boundary may establish grouping
without a spacing difference; make the relationship unambiguous.
**Sources:** [Proximity](https://lawsofux.com/law-of-proximity/),
[Common region](https://lawsofux.com/law-of-common-region/).
## UX-05 — Appearance carries consistent meaning (SHOULD)
**Applies:** repeated components, status colors, and action hierarchies.
**Behavior:** give equivalent actions and states consistent treatment. Reserve
distinct emphasis for meaningful priority or differences; never rely on color
alone to convey status.
**Check:** compare repeated controls across routes and themes; confirm equal
appearances do not imply incompatible behaviors.
**Exception:** context can change prominence without changing a control's
meaning; document intentional variants in the component system.
**Source:** [Similarity](https://lawsofux.com/law-of-similarity/).
## UX-06 — Reduce memory burden (SHOULD)
**Applies:** multistep tasks, forms, navigation, and comparison.
**Behavior:** keep labels, selected values, requirements, and relevant prior
choices visible or easily retrievable. Chunk content by meaning.
**Check:** complete the task without memorizing information from an earlier
screen; verify returning to a step preserves recoverable input.
**Exception:** expert shortcuts may supplement a discoverable path. Do not
derive a seven-item interface limit from a working-memory principle.
**Sources:** [Miller's Law and its cautions](https://lawsofux.com/millers-law/),
[Nielsen's heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/).
## UX-07 — Feedback and recovery (MUST)
**Applies:** operations that change state or can fail.
**Behavior:** show pending, success, and failure truthfully. Explain recovery,
preserve recoverable input, prevent accidental duplicate submissions, and
provide cancel or undo when the operation supports it. Match confirmation
friction to the consequence of an error. Optimistic UI needs failure handling.
**Check:** exercise slow, failed, and repeated requests; verify the interface
does not claim completion prematurely or leave the user stranded.
**Exception:** instantaneous local actions need no artificial loading state.
An unavailable recovery operation must not be offered as a working control.
**Source:** [Nielsen's heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/).
## Applying and resolving rules
Prefer measured task outcomes over a heuristic when they conflict. For
example, moving a destructive action closer may reduce pointer travel but
increase accidental activation; task safety takes priority. Record consequential
tradeoffs briefly. Do not use a law's name as evidence that a design works.
@@ -0,0 +1,103 @@
# Site completeness
## Scope and inventory (MUST)
For a new public site or complete public-site redesign, implement the baseline
below, reusing valid existing pages and integrations. These are this skill's
delivery requirements; the presence of a row does not imply a universal legal
obligation. For internal tools, targeted repairs, and prototypes, apply the
scope rules in [SKILL.md](../SKILL.md). Existing organization-wide privacy or
support destinations may be linked when they actually cover this service.
Keep a compact inventory: item, route or location, applicability, verified
content source, implementation, and verification result. A missing business
fact is unresolved work, not a reason to mark a required page inapplicable.
Ask for necessary facts while building the rest. Do not publish placeholders
as finished business or policy content.
| ID | Item and applicability | Required implementation | Acceptance check |
| --- | --- | --- | --- |
| SITE-01 | 404: every routed site/app | A recognizable not-found view with explanation, useful home/navigation links, and the normal accessible shell where appropriate. Preserve the unknown URL instead of silently redirecting to home. | Open an unknown nested URL directly and by client navigation. Check recovery links; verify HTTP 404 on the serving layer where supported. A static SPA that returns 200 must disclose that hosting limitation. |
| SITE-02 | About: public-site baseline | A dedicated page explaining who operates the site, its purpose, and relevant factual background, linked from navigation or footer. | Route loads directly; identity agrees with Contact, privacy, and footer. No invented team, credentials, statistics, or endorsements. |
| SITE-03 | Contact: public-site baseline | A dedicated page with at least one real, owner-supplied contact method. Implement all supplied, intended public methods: email, phone, address, support URL, or verified social links as appropriate. | Check mailto/tel/link destinations and accessible names; display a readable/copyable address or number. Do not invent missing methods or publish private contact details. |
| SITE-04 | Contact form: when included | Working delivery integration, labels, minimal required fields, useful validation, pending/error/success states, duplicate-submit protection, and privacy information at collection. A working direct contact method is an acceptable alternative when a form is not required. | Use a mock or authorized test destination to verify success and failure; preserve recoverable input on error. Never display success after only a timer, or send live messages without authorization. |
| SITE-05 | Privacy notice: public-site baseline; also wherever personal data is collected | A discoverable page covering the service's actual processing, with additional notice at collection points. Follow the privacy section below. | Compare text against forms, analytics, embeds, accounts, hosting/logging, and service providers. No generic claims of collecting nothing without evidence. |
| SITE-06 | Cookie/storage information and consent: according to actual technologies and applicable rules | Inventory cookies and similar storage/access technologies, purposes, providers, and duration. Implement the consent behavior below where consent is required; disclose exempt use appropriately. | Inspect actual requests and storage in a fresh session, after each choice, and after withdrawal. A visible banner alone does not pass. |
| SITE-07 | Shared footer: public-site baseline | About, Contact, Privacy, applicable policy and cookie-preference links, actual rights-holder name, and dynamic copyright. Use a shared component/configuration so routes agree. | Follow every link from an ordinary page and the 404 view; test wrapping, keyboard access, and year behavior. No empty hrefs or placeholder links. |
| SITE-08 | Error recovery: where runtime operations can fail | A suitable route/component fallback with recovery navigation, retry only when meaningful, and no sensitive diagnostics in public copy. | Exercise a failed request or rendering failure; the user can recover without losing avoidable input. Do not label permission/network errors as 404s without a deliberate access-disclosure policy. |
| SITE-09 | Page identity and navigation: all full sites | Accurate page titles, document language, meaningful headings, navigation/current-location cues, and supplied site identity assets. For indexable public pages, add appropriate descriptions and intended canonical URLs. | Test direct loads, reloads, deep links, back/forward, internal links, and titles after navigation. Do not index private content; robots directives are not access control. |
| SITE-10 | Additional policies and help: business-dependent | Implement applicable terms, refunds/returns/shipping, subscription cancellation, account recovery/deletion, accessibility/help, or jurisdiction-specific business disclosures when the service needs them. Reuse accurate existing policies. | Map each item to an actual business feature or applicable requirement. Verify destinations and promised workflows; obtain missing factual terms instead of inventing them. |
## PRIV-01 — Truthful privacy information (MUST when applicable)
Establish the operator/controller and privacy contact, what data is collected,
purposes and legal bases, recipients, retention periods or criteria, relevant
international transfers, and applicable rights and complaint routes. Address
indirect collection or automated decisions where used. Inform people at
collection and link the full notice. Use clear language for the audience.
Use verified operational facts and supplied policy decisions; an agent must
not invent a lawful basis, retention promise, jurisdiction, or legal entity.
If these facts are missing, prepare a clearly identified draft and list the
missing inputs. Do not mark policy content ready to publish until resolved.
A privacy page and banner do not establish legal compliance by themselves.
Source: [EDPB guidance on transparency and individual rights](https://www.edpb.europa.eu/sme/be-compliant/respect-individuals-rights_en).
Check current applicable requirements for the actual operator and audience;
this is a content and implementation checklist, not a universal policy text.
## CONSENT-01 — Consent that controls behavior (MUST where required)
Cookie and similar-technology rules arise from applicable ePrivacy/national
rules as well as GDPR where personal data is processed. Determine applicability
from the technology, purpose, and jurisdiction; do not assume every site needs
a banner or that a technology called "analytics" is automatically exempt.
This skill uses the following implementation defaults for consent-required use:
- Block consent-required scripts, embeds, pixels, requests, and storage until
the relevant affirmative choice. Cover tag managers and indirect loaders.
- Offer equally accessible Accept all, Reject nonessential, and Preferences
controls in the initial interface. No preselected optional purposes, implied
consent from scrolling/dismissal, or visually suppressed refusal.
- Explain purposes/providers and distinguish necessary use from optional use.
Enable only selected purposes, and persist the choice with a policy/config
version and appropriate lifetime. Use the minimum consent record needed.
- Provide a persistent Cookie preferences link. Withdrawal stops future
consent-required activity and clears controlled optional storage where
possible; handle already-loaded integrations and reload if needed. Do not
imply withdrawal reverses earlier disclosures to third parties.
- If consent storage or the consent manager fails, leave optional activity
off while keeping core content usable. Reconcile expired choices and changed
purposes before enabling affected integrations.
Verify fresh visit, reject, selective accept, accept all, reload, withdrawal,
expired/changed preference, and unavailable storage. Inspect network activity
and storage, not just the controls. Check keyboard operation and narrow layouts.
If there is no consent-required use, record that finding; do not add tracking
or an unnecessary consent interruption just to satisfy a checklist.
Sources: [CNIL cookie guidance](https://www.cnil.fr/fr/cookies-et-autres-traceurs/regles/cookies/lignes-directrices-modificatives-et-recommandation),
[CNIL implementation guidance](https://www.cnil.fr/fr/cookies-et-autres-traceurs/regles/cookies/comment-mettre-mon-site-web-en-conformite),
[CNIL consent guidance](https://cnil.fr/fr/les-bases-legales/consentement).
The defaults above are engineering choices supporting consent; validate
jurisdiction-specific details against current regulator guidance.
## YEAR-01 — Shared dynamic copyright (MUST for current copyright notices)
Derive the current year from a shared date source/component and use it in the
footer and every other current copyright notice, including shared layouts and
generated templates in scope. Never scatter hard-coded current-year strings.
Use the actual rights-holder name. Include a start-year range only when that
start year is verified; render one year when start and current years match.
Choose an update mechanism appropriate to the stack: request-time rendering,
client refresh with consistent initial hydration, or automatic static rebuild
and cache refresh across the year boundary. A build-time date without a
rollover/update mechanism can become stale. Ensure a readable fallback in the
supported no-JavaScript experience and avoid server/client timezone mismatch.
Check December 31 and January 1 with a controlled clock, including cached/static
output and each shared placement. State the timezone used. Do not change real
publication dates, policy effective/review dates, historical notices, or
third-party attribution years just because the calendar changed.
@@ -0,0 +1,70 @@
# Verification and completion
## Evidence appropriate to the task (MUST)
For each relevant requirement record its ID or clear name, result, evidence,
and unresolved limitation. Use the existing project report or a concise
handoff; a small repair does not need a separate audit document.
- **pass:** observed behavior satisfies the requirement; identify the check.
- **fail:** observed behavior violates it; identify the problem.
- **not applicable:** the applicability condition is absent; explain why.
- **not verified:** needed access, facts, or test capability are missing.
An explicit scope exclusion is recorded as excluded with its consequence;
it does not turn an applicable requirement into an inapplicable one. Do not
average failed functional/accessibility checks into a passing aesthetic score.
## Review sequence
1. **Structure and content:** check hierarchy, truthful copy, semantic tokens,
route inventory, real link destinations, and relevant component states.
2. **Rendered behavior:** inspect representative narrow and wide viewports,
around layout transitions, with long/empty content, image/font failure,
zoom, reduced motion, and supported themes/languages as relevant.
3. **Interactions:** exercise the main task, keyboard path, submission states,
recovery, and repeated actions. Use a mock or authorized test destination
for messaging, purchases, and other external effects.
4. **Site completeness:** for site-level work, verify the inventory in
[site completeness](site-completeness.md), including direct unknown routes,
Contact, privacy, consent behavior, footer links, and year rollover.
5. **Project checks:** run relevant existing build, lint, accessibility, and
behavior checks. Add tests when they verify consequential behavior such as
consent gating or submission recovery; avoid tests that merely match copy.
6. **Critique and recheck:** correct observed problems and rerun affected
checks. Stop when the scoped acceptance conditions are met; do not add
repeated redesign rounds just to seek novelty.
Screenshots support visual claims. DOM inspection supports structural claims.
Keyboard traces support interaction claims. Network/storage checks support
consent claims. Mock responses do not prove a production delivery integration.
State those limits instead of treating one kind of evidence as another.
## Completion gate
For implemented work, do not declare the site or feature fully complete while
an applicable requirement is failed or not verified. Deliver the usable work
and name remaining limitations precisely. Do not block independent work just
because one integration or business fact is missing. Publication is governed
by the user's authorization and project workflow, not this skill.
For reviews or design-only work, completion means the requested assessment or
design is delivered with findings and limitations; it does not mean the
underlying product has passed implementation checks.
## Scenario checks for maintaining this skill
Use contrasting scenarios when substantially revising the instructions.
These describe expected decisions, not a requirement to build all scenarios
for each frontend task. Distinguish a reasoning walkthrough from an executed
evaluation with a rendered artifact.
| Scenario | Expected behavior |
| --- | --- |
| New public studio site, supplied business facts, no optional tracking | Distinctive direction; working About, Contact, privacy, footer, dynamic year, and 404. Inspect actual data use; no unnecessary consent banner. |
| Public site with consent-required analytics and a third-party video embed | Inventory both integrations; gate them before consent, permit selective choice, persist rejection, and stop future activity after withdrawal. |
| Dense internal operations dashboard | Reuse product conventions, preserve frequent controls, include relevant failure/focus/empty states, and adapt genuine two-dimensional data appropriately. Public marketing pages need a scope reason. |
| Fix one form field in an established app | Preserve the design system; fix semantics, labeling, and related error/layout behavior. Do not launch a site-wide redesign. |
| New public site with unknown operator/contact/retention facts | Ask for required facts; build independent structure; identify draft policy/contact work. Do not invent facts or claim publication readiness. |
| Static site with multiple copyright placements | Use a shared year source with a rollover/update strategy; exercise year boundary and cache behavior. Leave policy effective dates intact. |
| No browser or network-inspection capability | Perform useful implementation/static checks and explicitly mark visual, interaction, or consent checks not verified. |
@@ -0,0 +1,90 @@
# Visual system and interface writing
## VIS-01 — Subject-specific direction (SHOULD)
Ground visual decisions in the product, audience, content, and existing brand.
For a new direction, describe its composition, type roles, palette roles, and
one or two subject-specific choices. For an extension, inspect and reuse the
established system. Do not invent a new brand for a small repair.
Check whether imagery, hierarchy, density, and vocabulary serve the actual
brief. Visual novelty is not an acceptance test. Cream palettes, dark themes,
serifs, gradients, rounded cards, and uppercase labels are valid when they
have a purpose; none should appear merely out of habit.
## VIS-02 — Semantic tokens (SHOULD)
Reuse existing tokens first. For new systems define a compact set of roles:
| Area | Useful roles | Verification |
| --- | --- | --- |
| Color | canvas, surface, text, muted text, action, danger, focus | Check actual foreground/background pairs in relevant states and themes. |
| Type | display, heading, body, label, data | Repeated roles use consistent size, weight, and line height. |
| Space | component padding, related-item gap, group gap, section gap | Grouping survives wrapping and long content. |
| Geometry | content width, gutter, radius, elevation | Width and containment follow content priority; depth signals relationships. |
| Motion | feedback purpose, duration, easing, reduced-motion behavior | State remains understandable with motion reduced or removed. |
Add a token or variant for a repeated meaning, not every isolated value. A
small spacing scale based on 4 or 8 units is a possible house convention,
not a design law. Avoid competing CSS rules that conceal the intended spacing.
## VIS-03 — Typography and reading (SHOULD)
Choose type for legibility, tone, language coverage, loading cost, and the
existing brand. One family can supply hierarchy; a second needs a clear role.
Define a coherent scale instead of inventing each heading independently.
House starting points for running prose: about 4575 characters per line and
1.41.6 line height. Adjust for the actual font, script, size, and content.
These are preferences, not accessibility thresholds. Controls, data tables,
and display text need their own metrics. Do not infer leading solely from
whether a font has serifs.
Inspect actual text, fallback fonts, long headings, and zoom. Avoid clipping,
fixed-height text containers, and shrinking text to force a layout to fit.
Use logical alignment appropriate to the language; reserve centered text for
content that remains easy to scan. Use tabular numerals when numeric alignment
helps comparison. Establish a fallback if a custom font fails.
## VIS-04 — Composition and restraint (SHOULD)
Give the primary task or message a clear place in the hierarchy. A marketing
site may benefit from an expressive opening; a work tool may need immediate
access to data and controls. Use real content to determine layout and density.
Outlines, dividers, labels, numbering, and cards should encode information.
Number items when sequence or rank matters. Reserve repeated containers for
content that is meaningfully comparable. Concentrate bold expression where
it helps the brief, and remove decoration that competes with the task.
Check wide and narrow compositions, long or missing content, image crops,
and consistent alignment. Choose layout transitions when content needs them,
then test around those transitions; device names alone do not define breakpoints.
## VIS-05 — Purposeful motion (SHOULD; reduced-motion support MUST)
Use motion to explain feedback, continuity, or a meaningful change. Keep
non-user-triggered effects restrained. Do not delay access to content for an
entrance animation. Respect reduced-motion preferences by removing or
replacing nonessential movement while preserving the information conveyed.
Verify the changed states with reduced motion enabled and ordinary animation
disabled. Hover may enhance an interaction but cannot be its only entry point.
## VIS-06 — Copy is functional content
Truthful behavior is a requirement; tone guidance is a heuristic.
Name actions by their outcome: "Save changes", "Download report", "Send
message". Keep vocabulary consistent through the flow, including success and
error messages. Use audience-appropriate language; technical terminology is
appropriate when it helps that audience make a decision.
Use concise active sentences and sentence case by default. Errors identify
the problem and recovery; empty states explain the condition and useful next
step. Distinguish first use, no matching results, and unavailable data.
Use supplied business facts. Mark sample content as sample in prototypes;
do not fabricate testimonials, customer counts, response times, team members,
contact methods, or privacy promises for a finished site. Maintain consistent
business identity and shared text through common configuration/components.