@victorolorunfemi/shared-frontend-skills 0.0.0-stage → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Victor Olorunfemi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,2 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # shared-frontend-skills
2
+ A collection of shared frontend skills, containing architectural & coding best practices i use across projects
package/dist/cli.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
package/dist/cli.js ADDED
@@ -0,0 +1,80 @@
1
+ #!/usr/bin/env node
2
+ import chalk from 'chalk';
3
+ import fs from 'node:fs/promises';
4
+ import path from 'node:path';
5
+ import readline from 'node:readline/promises';
6
+ import { stdin as input, stdout as output } from 'node:process';
7
+ import { fileURLToPath } from 'node:url';
8
+ const __filename = fileURLToPath(import.meta.url);
9
+ const __dirname = path.dirname(__filename);
10
+ const SOURCE_SKILLS_DIR = path.resolve(__dirname, '../skills');
11
+ const TARGET_SKILLS_DIR = path.resolve(process.cwd(), '.claude/skills');
12
+ async function getAvailableSkills() {
13
+ try {
14
+ const entries = await fs.readdir(SOURCE_SKILLS_DIR, { withFileTypes: true });
15
+ return entries
16
+ .filter((entry) => entry.isDirectory())
17
+ .map((entry) => entry.name)
18
+ .sort();
19
+ }
20
+ catch {
21
+ console.error(chalk.red('\n✖ Failed to locate bundled skills directory.'));
22
+ process.exit(1);
23
+ }
24
+ }
25
+ async function promptConfirmation(question) {
26
+ const rl = readline.createInterface({ input, output });
27
+ try {
28
+ while (true) {
29
+ const answer = await rl.question(question);
30
+ const normalized = answer.trim().toLowerCase();
31
+ if (normalized === 'y' || normalized === 'yes') {
32
+ return true;
33
+ }
34
+ if (normalized === 'n' || normalized === 'no') {
35
+ return false;
36
+ }
37
+ console.log(chalk.yellow(' Please enter Y or N.'));
38
+ }
39
+ }
40
+ finally {
41
+ rl.close();
42
+ }
43
+ }
44
+ async function installSkills(skills) {
45
+ await fs.mkdir(TARGET_SKILLS_DIR, { recursive: true });
46
+ for (const skill of skills) {
47
+ const srcPath = path.join(SOURCE_SKILLS_DIR, skill);
48
+ const destPath = path.join(TARGET_SKILLS_DIR, skill);
49
+ await fs.rm(destPath, { recursive: true, force: true });
50
+ await fs.cp(srcPath, destPath, { recursive: true });
51
+ console.log(`${chalk.green(' ✔')} Installed ${chalk.cyan(skill)}`);
52
+ }
53
+ }
54
+ async function main() {
55
+ console.log(chalk.bold.blue('\nFrontend Agent Skills Installer\n'));
56
+ const skills = await getAvailableSkills();
57
+ if (skills.length === 0) {
58
+ console.log(chalk.yellow('No skills found to install.'));
59
+ process.exit(0);
60
+ }
61
+ console.log(chalk.white('Target directory: ') + chalk.dim(TARGET_SKILLS_DIR));
62
+ console.log(chalk.white('\nThe following skills will be installed:\n'));
63
+ for (const skill of skills) {
64
+ console.log(` ${chalk.gray('•')} ${chalk.cyan(skill)}`);
65
+ }
66
+ console.log('');
67
+ const confirmed = await promptConfirmation(chalk.bold('Proceed with installation? (Y/N): '));
68
+ if (!confirmed) {
69
+ console.log(chalk.yellow('\nInstallation cancelled. No files were modified.\n'));
70
+ process.exit(0);
71
+ }
72
+ console.log('');
73
+ await installSkills(skills);
74
+ console.log(chalk.bold.green(`\n✔ Successfully installed ${skills.length} skills into .claude/skills/\n`));
75
+ }
76
+ main().catch((err) => {
77
+ console.error(chalk.red('\n✖ Unexpected error during installation:'), err);
78
+ process.exit(1);
79
+ });
80
+ //# sourceMappingURL=cli.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,45 @@
1
1
  {
2
2
  "name": "@victorolorunfemi/shared-frontend-skills",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.0.1",
4
+ "description": "A collection of shared frontend skills, containing architectural & coding best practices.",
5
+ "main": "dist/index.js",
6
+ "types": "dist/index.d.ts",
7
+ "bin": {
8
+ "shared-frontend-skills": "./dist/cli.js"
9
+ },
10
+ "files": [
11
+ "dist",
12
+ "skills"
13
+ ],
14
+ "publishConfig": {
15
+ "access": "public"
16
+ },
17
+ "keywords": [],
18
+ "author": "",
19
+ "license": "ISC",
20
+ "devEngines": {
21
+ "packageManager": {
22
+ "name": "pnpm",
23
+ "version": "12.18.0",
24
+ "onFail": "download"
25
+ }
26
+ },
27
+ "type": "module",
28
+ "devDependencies": {
29
+ "@biomejs/biome": "^2.6.8",
30
+ "@types/node": "^26.6.6",
31
+ "typescript": "^7.0.2"
32
+ },
33
+ "dependencies": {
34
+ "chalk": "^6.0.1"
35
+ },
36
+ "engines": {
37
+ "node": ">=20.0.0"
38
+ },
39
+ "scripts": {
40
+ "test": "echo \"Error: no test specified\" && exit 1",
41
+ "build": "tsc",
42
+ "lint": "biome lint src",
43
+ "lint:write": "biome lint src --write"
44
+ }
6
45
  }
@@ -0,0 +1,191 @@
1
+ ---
2
+ name: frontend-accessibility
3
+ description: Standards and guidelines for building, reviewing, and testing accessible frontend applications. Enforce WCAG 2.2 Level AA, semantic HTML, ARIA, keyboard navigation, focus management, accessible forms, screen reader compatibility, and inclusive interaction patterns. Use when building UI components, implementing interactions, reviewing frontend code, or auditing web applications for accessibility.
4
+ ---
5
+
6
+ # Frontend Accessibility (a11y) Standards & Guidelines
7
+
8
+ ## 1. Core Accessibility Principles
9
+
10
+ - **Accessibility by Default**: Treat accessibility as a fundamental engineering requirement, not a final polishing step. Consider accessibility during component design, implementation, testing, and review.
11
+ - **WCAG Compliance**: Target WCAG 2.2 Level AA unless the project explicitly requires a higher standard.
12
+ - **Inclusive Design**: Ensure interfaces work for people using keyboards, screen readers, magnification, voice control, and other assistive technologies.
13
+ - **Perceivable, Operable, Understandable, Robust (POUR)**: Apply the four WCAG principles when evaluating interface behavior and content.
14
+ - **Progressive Enhancement**: Prefer native browser capabilities and ensure essential functionality remains available without relying exclusively on JavaScript or visual presentation.
15
+ - **No Accessibility Regressions**: Changes to shared components, design systems, and interaction patterns must preserve existing accessibility behavior.
16
+
17
+ ## 2. Semantic HTML & Native Primitives
18
+
19
+ - **Use Native Elements First**: Prefer native HTML elements such as `<button>`, `<a href="...">`, `<input>`, `<select>`, and `<dialog>` over generic `<div>` or `<span>` elements with custom interaction handlers.
20
+ - **Correct Element Semantics**:
21
+ - Use `<button>` for actions and state changes.
22
+ - Use `<a>` for navigation.
23
+ - Use `<nav>` for navigation regions.
24
+ - Use `<main>` for the primary page content.
25
+ - Use `<form>` for user-submitted data.
26
+ - Use `<ul>`, `<ol>`, and `<li>` for lists.
27
+ - Use appropriate table elements for tabular data.
28
+ - **Document Structure**: Use meaningful landmarks such as `<header>`, `<nav>`, `<main>`, `<aside>`, and `<footer>` to establish page structure.
29
+ - **Heading Hierarchy**: Use headings (`<h1>` to `<h6>`) to communicate logical content structure. Do not select heading levels merely for visual styling. Avoid unnecessary heading-level jumps.
30
+ - **Accessible Names**: Every interactive element must have a meaningful accessible name that describes its purpose.
31
+ - **Avoid Non-Semantic Interactions**: Do not make static elements interactive unless there is a strong reason and the required keyboard, focus, role, and state behavior can be implemented correctly.
32
+
33
+ ## 3. Keyboard Navigation & Focus Management
34
+
35
+ - **Keyboard Accessibility**: All interactive functionality must be usable with a keyboard without requiring a mouse or touch input.
36
+ - **Logical Focus Order**: Ensure keyboard focus follows a predictable order that corresponds to the page's content and interaction flow.
37
+ - **Visible Focus Indicators**: Never remove browser focus outlines without providing an equally visible or better alternative. Use clear `:focus-visible` styles where appropriate.
38
+ - **Focus Visibility**: Ensure focused elements are not hidden behind sticky headers, overlays, or other content.
39
+ - **Avoid Positive Tab Indexes**: Do not use positive `tabIndex` values to manipulate focus order. Use native document order and `tabIndex={0}` or `tabIndex={-1}` only when appropriate.
40
+ - **Focus Management**:
41
+ - Move focus when an interaction requires a new context, such as opening a modal dialog.
42
+ - Restore focus to the appropriate trigger or logical destination when a modal closes.
43
+ - Manage focus after route changes, form submissions, and significant content transitions where necessary.
44
+ - Avoid unexpected focus changes during ordinary rendering.
45
+ - **Modal Dialogs**:
46
+ - Move focus into the dialog when it opens.
47
+ - Keep keyboard focus within the modal while it is active.
48
+ - Support Escape to close when appropriate.
49
+ - Make background content unavailable to interaction while the modal is active.
50
+ - Return focus to the triggering element or another logical destination when closed.
51
+ - Prefer native `<dialog>` where its behavior meets the requirements.
52
+ - **Custom Widgets**: Implement appropriate keyboard interaction patterns for tabs, menus, comboboxes, listboxes, and other composite widgets. Do not assume every widget should use the same keyboard behavior.
53
+
54
+ ## 4. ARIA & Accessible Interaction Patterns
55
+
56
+ - **First Rule of ARIA**: Do not use ARIA when native HTML already provides the required semantics and behavior.
57
+ - **Correct Roles**: Use ARIA roles only when native HTML cannot adequately express the component's semantics.
58
+ - **Accessible Names and Descriptions**: Ensure interactive controls have meaningful accessible names. Use `aria-label`, `aria-labelledby`, and `aria-describedby` appropriately.
59
+ - **State Synchronization**: Keep ARIA states synchronized with actual UI state. Examples include:
60
+ - `aria-expanded`
61
+ - `aria-selected`
62
+ - `aria-checked`
63
+ - `aria-pressed`
64
+ - `aria-disabled`
65
+ - `aria-invalid`
66
+ - **Relationships**: Use attributes such as `aria-controls` and `aria-describedby` only when they reference valid, relevant elements.
67
+ - **Live Regions**: Use `aria-live`, `role="status"`, and `role="alert"` when dynamic updates need to be communicated to assistive technologies.
68
+ - **Hidden Content**:
69
+ - Use `aria-hidden="true"` only when content should be excluded from the accessibility tree.
70
+ - Never apply `aria-hidden="true"` to an element containing interactive or focusable descendants that users can still reach.
71
+ - Do not use `display: none` or `visibility: hidden` for content that must remain available to screen readers.
72
+ - **Established Patterns**: Follow the WAI-ARIA Authoring Practices Guide for custom widgets instead of inventing interaction patterns.
73
+
74
+ ## 5. Forms & Interactive Inputs
75
+
76
+ - **Explicit Labels**: Every form control must have an accessible name, preferably through an associated `<label>` using `htmlFor` or a wrapping label.
77
+ - **Placeholder Restrictions**: Placeholder text is not a substitute for a label. Do not rely on placeholders as the only source of instructions.
78
+ - **Instructions and Requirements**:
79
+ - Clearly communicate required fields and expected input formats.
80
+ - Use appropriate native input types and attributes, including `type`, `required`, `min`, `max`, and `autocomplete`.
81
+ - Do not communicate required or optional fields through color alone.
82
+ - **Error Identification**:
83
+ - Clearly identify invalid fields.
84
+ - Use `aria-invalid="true"` when a field contains an error.
85
+ - Associate relevant error messages using `aria-describedby`.
86
+ - Ensure error messages explain what went wrong and how to correct it.
87
+ - **Validation Feedback**: Do not rely exclusively on color, icons, or visual styling to communicate validation results.
88
+ - **Error Summaries**: For forms with multiple errors, consider providing an error summary with links to the affected fields.
89
+ - **Submission Feedback**: Communicate successful submissions, processing states, and failures to assistive technologies where appropriate.
90
+ - **Custom Controls**: Custom dropdowns, date pickers, switches, and other controls must preserve accessible names, states, keyboard interaction, and focus behavior.
91
+
92
+ ## 6. Screen Readers & Accessible Content
93
+
94
+ - **Image Alternatives**:
95
+ - Provide descriptive `alt` text for informative images.
96
+ - Use `alt=""` for purely decorative images.
97
+ - Avoid redundant descriptions when adjacent text already communicates the same information.
98
+ - For complex images such as charts and diagrams, provide an equivalent detailed text explanation.
99
+ - **Icon-Only Controls**: Provide accessible names for icon-only buttons and links. Do not assume an icon's visual meaning is sufficient.
100
+ - **Link Purpose**: Link text must communicate its destination or purpose. Avoid ambiguous labels such as "click here" when they do not provide sufficient context.
101
+ - **Screen Reader-Only Content**: Use established `.sr-only` or `.visually-hidden` utilities for context that should be available to assistive technologies but visually hidden.
102
+ - **Dynamic Content**: Announce meaningful asynchronous updates, such as submission results, loading completion, and status changes, without unnecessarily interrupting the user.
103
+ - **Language**: Set the document language using the appropriate `lang` attribute. Identify language changes within content where necessary.
104
+ - **Abbreviations and Instructions**: Ensure technical abbreviations, symbols, and instructions are understandable in context.
105
+
106
+ ## 7. Visual Accessibility & Responsive Presentation
107
+
108
+ - **Text Contrast**: Meet WCAG AA contrast requirements:
109
+ - Normal text: minimum 4.5:1.
110
+ - Large text: minimum 3:1.
111
+ - **Non-Text Contrast**: Meaningful UI components, graphical objects, and visual states must meet the applicable 3:1 contrast requirement against adjacent colors.
112
+ - **Color Independence**: Never rely on color alone to communicate information, errors, status, or interaction states. Combine color with text, icons, patterns, or other visual indicators.
113
+ - **Text Resizing**: Support text resizing up to 200% without loss of content or functionality.
114
+ - **Reflow**: Ensure content remains usable at narrow viewport widths and high zoom levels without unnecessary horizontal scrolling.
115
+ - **Text Spacing**: Avoid fixed-height text containers that clip content when users adjust line height, letter spacing, or word spacing.
116
+ - **Responsive Layouts**: Ensure responsive changes do not hide essential content or make controls inaccessible.
117
+ - **Touch Targets**: Follow WCAG 2.2 target-size requirements. Aim for at least 24 × 24 CSS pixels for pointer targets, subject to the standard's exceptions; larger targets are preferable for usability.
118
+ - **Motion and Animation**:
119
+ - Respect `prefers-reduced-motion`.
120
+ - Avoid unnecessary flashing, excessive movement, and distracting animations.
121
+ - Provide controls to pause, stop, or hide qualifying moving or automatically updating content.
122
+ - Do not communicate essential information exclusively through animation.
123
+
124
+ ## 8. Media, Audio & Video
125
+
126
+ - **Captions**: Provide synchronized captions for prerecorded video containing meaningful audio.
127
+ - **Live Captions**: Provide live captions for live audio content where required.
128
+ - **Transcripts**: Provide text alternatives for audio-only content and useful transcripts for multimedia where appropriate.
129
+ - **Audio Descriptions**: Ensure meaningful visual information in prerecorded video is available through audio description or an equivalent alternative when required.
130
+ - **Media Controls**: Use accessible native media controls or ensure custom controls support keyboard navigation and screen readers.
131
+ - **Autoplay**: Avoid automatically playing audio or video with sound. Provide appropriate controls for automatically moving content.
132
+
133
+ ## 9. React & Component Implementation
134
+
135
+ - **Semantic Components**: Shared React components must preserve native HTML semantics and expose accessible properties through their public APIs.
136
+ - **Component Composition**: Ensure accessibility is not lost when components are wrapped, composed, or reused.
137
+ - **Refs and Focus**: Use refs to manage focus when necessary, such as focusing an invalid field or moving focus into a dialog.
138
+ - **Portals**: Components rendered through React portals must preserve correct focus management, accessible relationships, and modal behavior.
139
+ - **Controlled State**: Keep visual state, component behavior, and ARIA attributes synchronized.
140
+ - **Conditional Rendering**: Ensure dynamically mounted or removed elements do not leave focus in an invalid or inaccessible location.
141
+ - **Event Handling**: Do not rely exclusively on mouse events such as `onClick` attached to non-interactive elements. Prefer native controls and their built-in keyboard behavior.
142
+ - **Reusable Components**: Accessibility requirements must be built into shared components rather than repeatedly delegated to consuming pages.
143
+ - **Component APIs**: Avoid APIs that make it easy to omit essential accessibility information, such as accessible labels for icon-only controls.
144
+
145
+ ## 10. Accessibility Testing & Validation
146
+
147
+ - **Automated Testing**: Use accessibility testing tools such as axe-core, jest-axe, or equivalent tooling where appropriate.
148
+ - **Component Testing**: Test accessible names, roles, states, relationships, validation messages, and keyboard behavior.
149
+ - **Keyboard Testing**: Manually verify navigation using Tab, Shift+Tab, Enter, Space, Escape, and relevant arrow-key interactions.
150
+ - **Screen Reader Testing**: Test important user flows with supported screen readers and browsers. Examples include NVDA with Firefox or Chrome, and VoiceOver with Safari.
151
+ - **Visual Testing**: Check color contrast, focus indicators, zoom, text resizing, reflow, and reduced-motion behavior.
152
+ - **Form Testing**: Verify labels, instructions, error associations, validation feedback, and successful submission announcements.
153
+ - **Regression Testing**: Include accessibility checks for shared components and critical user journeys in the test suite.
154
+ - **Manual Verification**: Do not treat automated scanner results as proof of WCAG conformance. Automated tools cannot detect every accessibility issue.
155
+ - **User-Centered Validation**: Where practical, validate important workflows with people who use assistive technologies.
156
+
157
+ ## 11. Accessibility Review & Reporting
158
+
159
+ When reviewing frontend code for accessibility:
160
+
161
+ - Identify the affected component, page, or user flow.
162
+ - Explain the accessibility issue and its impact on users.
163
+ - Reference the relevant WCAG success criterion when applicable.
164
+ - Classify findings by severity:
165
+ - **Critical**: A major barrier that prevents users from accessing essential functionality.
166
+ - **High**: A significant accessibility issue affecting important interactions or content.
167
+ - **Medium**: An issue that creates friction or makes an interaction unnecessarily difficult.
168
+ - **Low**: A minor usability or consistency improvement.
169
+ - Provide actionable remediation guidance.
170
+ - Distinguish confirmed accessibility failures from potential risks that require manual verification.
171
+ - Do not report ARIA attributes as inherently beneficial; evaluate whether they improve or damage the actual accessibility experience.
172
+
173
+ ## 12. Final Accessibility Checklist
174
+
175
+ Before considering an implementation complete, verify:
176
+
177
+ - [ ] Native semantic HTML is used wherever possible.
178
+ - [ ] Page landmarks and heading structure are logical.
179
+ - [ ] Every interactive element has an accessible name and appropriate semantics.
180
+ - [ ] All functionality is keyboard accessible.
181
+ - [ ] Focus order is predictable and focus indicators are visible.
182
+ - [ ] Dialogs and overlays manage focus correctly.
183
+ - [ ] ARIA roles, states, and relationships are valid and synchronized.
184
+ - [ ] Forms have accessible labels, instructions, and error feedback.
185
+ - [ ] Informative images have appropriate text alternatives.
186
+ - [ ] Dynamic updates are communicated to assistive technologies where necessary.
187
+ - [ ] Text and non-text contrast meet applicable WCAG AA requirements.
188
+ - [ ] Content remains usable with zoom, text resizing, and reflow.
189
+ - [ ] Motion and animation respect user preferences.
190
+ - [ ] Important workflows have been tested with automated and manual accessibility checks.
191
+ - [ ] No known critical or high-severity accessibility barriers remain.