fecode-cli 1.1.3 → 1.2.0
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/README.md +92 -8
- package/dist/index.js +23293 -1
- package/dist/{node.browser-BsGbhAIw.js → node.browser-2EgZAKSy.js} +1 -1
- package/dist/{node.browser-B5CfqNxN.js → node.browser-B5Gur0wd.js} +1 -1
- package/dist/{node.browser-BWLpZywP.js → node.browser-BSlAsiSV.js} +1 -1
- package/dist/{node.browser-7pW7d9_e.js → node.browser-CdVAMgSg.js} +1 -1
- package/dist/{src-CxriUNOE.js → src-CSWdjU4j.js} +4836 -4522
- package/dist/{src-DBoGZaxi.js → src-DY3OmBmT.js} +6670 -4557
- package/dist/{src-B_Z8CdqT.js → src-DcYf8vsK.js} +4850 -4526
- package/dist/{src-Bhec3XmL.js → src-DkWmcv2Q.js} +6677 -4604
- package/package.json +5 -2
- package/skills/accessibility/SKILL.md +98 -98
- package/skills/css/SKILL.md +90 -90
- package/skills/frontend-debugging/SKILL.md +201 -201
- package/skills/frontend-design/SKILL.md +358 -358
- package/skills/frontend-performance/SKILL.md +89 -89
- package/skills/frontend-testing/SKILL.md +87 -87
- package/skills/nextjs/SKILL.md +75 -75
- package/skills/react/SKILL.md +213 -213
- package/skills/responsive-design/SKILL.md +190 -190
- package/skills/svelte/SKILL.md +86 -86
- package/skills/tailwind/SKILL.md +74 -74
- package/skills/ui-review/SKILL.md +245 -245
- package/skills/vue/SKILL.md +72 -72
- package/dist/App.d.ts +0 -33
- package/dist/App.js +0 -2224
- package/dist/approvalResolver.d.ts +0 -12
- package/dist/approvalResolver.js +0 -112
- package/dist/commands.d.ts +0 -11
- package/dist/commands.js +0 -33
- package/dist/error-qAR8Lv-R.js +0 -57
- package/dist/index.d.ts +0 -3
- package/dist/node.browser-C9Wg-Fje.js +0 -46
- package/dist/node.browser-CADgAblr.js +0 -46
- package/dist/node.browser-Cse19Rko.js +0 -47
- package/dist/node.browser-Cx8sZi1Z.js +0 -46
- package/dist/node.browser-DtPNhPGQ.js +0 -46
- package/dist/node.browser-DvjMZMaq.js +0 -46
- package/dist/node.browser-EewJmuUw.js +0 -46
- package/dist/node.browser-J7voHtuR.js +0 -10
- package/dist/src-4fKRO0jn.js +0 -31655
- package/dist/src-8kA-5Kbs.js +0 -31591
- package/dist/src-C8Oe06wn.js +0 -31580
- package/dist/src-D78uLcuc.js +0 -31573
- package/dist/src-EyWDnffN.js +0 -31636
- package/dist/src-dhvwrHAJ.js +0 -31590
- package/dist/ui/AppShell.d.ts +0 -14
- package/dist/ui/AppShell.js +0 -25
- package/dist/ui/ApprovalPrompt.d.ts +0 -31
- package/dist/ui/ApprovalPrompt.js +0 -55
- package/dist/ui/BlockedView.d.ts +0 -13
- package/dist/ui/BlockedView.js +0 -7
- package/dist/ui/CommandPalette.d.ts +0 -8
- package/dist/ui/CommandPalette.js +0 -18
- package/dist/ui/CurrentStepView.d.ts +0 -16
- package/dist/ui/CurrentStepView.js +0 -28
- package/dist/ui/DiagnosticsView.d.ts +0 -45
- package/dist/ui/DiagnosticsView.js +0 -23
- package/dist/ui/ExecutionTimeline.d.ts +0 -15
- package/dist/ui/ExecutionTimeline.js +0 -51
- package/dist/ui/ExecutionView.d.ts +0 -42
- package/dist/ui/ExecutionView.js +0 -20
- package/dist/ui/Header.d.ts +0 -15
- package/dist/ui/Header.js +0 -47
- package/dist/ui/HelpView.d.ts +0 -3
- package/dist/ui/HelpView.js +0 -35
- package/dist/ui/MessageBubble.d.ts +0 -9
- package/dist/ui/MessageBubble.js +0 -58
- package/dist/ui/PlanStep.d.ts +0 -16
- package/dist/ui/PlanStep.js +0 -71
- package/dist/ui/PlanView.d.ts +0 -26
- package/dist/ui/PlanView.js +0 -24
- package/dist/ui/ProgressBar.d.ts +0 -10
- package/dist/ui/ProgressBar.js +0 -14
- package/dist/ui/RecoveryView.d.ts +0 -20
- package/dist/ui/RecoveryView.js +0 -19
- package/dist/ui/ReplanView.d.ts +0 -16
- package/dist/ui/ReplanView.js +0 -21
- package/dist/ui/ResumeView.d.ts +0 -15
- package/dist/ui/ResumeView.js +0 -25
- package/dist/ui/RiskNotice.d.ts +0 -10
- package/dist/ui/RiskNotice.js +0 -21
- package/dist/ui/RunHistoryView.d.ts +0 -15
- package/dist/ui/RunHistoryView.js +0 -39
- package/dist/ui/StatusBar.d.ts +0 -16
- package/dist/ui/StatusBar.js +0 -104
- package/dist/ui/TaskInput.d.ts +0 -15
- package/dist/ui/TaskInput.js +0 -8
- package/dist/ui/ThinkingBlock.d.ts +0 -8
- package/dist/ui/ThinkingBlock.js +0 -13
- package/dist/ui/ThinkingIndicator.d.ts +0 -7
- package/dist/ui/ThinkingIndicator.js +0 -20
- package/dist/ui/TurnView.d.ts +0 -13
- package/dist/ui/TurnView.js +0 -11
- package/dist/ui/WorkspaceStatus.d.ts +0 -20
- package/dist/ui/WorkspaceStatus.js +0 -23
- package/dist/ui/index.d.ts +0 -26
- package/dist/ui/index.js +0 -26
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fecode-cli",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "FeCode - Interactive Terminal Coding Assistant",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -24,11 +24,14 @@
|
|
|
24
24
|
"test": "vitest run"
|
|
25
25
|
},
|
|
26
26
|
"dependencies": {
|
|
27
|
+
"@anthropic-ai/sdk": "^0.135.0",
|
|
27
28
|
"@google/genai": "^2.16.0",
|
|
29
|
+
"@modelcontextprotocol/sdk": "^1.32.1",
|
|
30
|
+
"@napi-rs/keyring": "^2.1.2",
|
|
28
31
|
"dotenv": "^16.6.1",
|
|
29
32
|
"ink": "^5.1.0",
|
|
30
33
|
"ink-text-input": "^6.0.0",
|
|
31
|
-
"openai": "^
|
|
34
|
+
"openai": "^7.57.0",
|
|
32
35
|
"react": "^18.3.1"
|
|
33
36
|
},
|
|
34
37
|
"devDependencies": {
|
|
@@ -1,98 +1,98 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: accessibility
|
|
3
|
-
description: Practical web accessibility implementation, ARIA semantics, keyboard navigation, and focus management.
|
|
4
|
-
category: accessibility
|
|
5
|
-
version: 2.1.0
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
## When to use
|
|
9
|
-
|
|
10
|
-
- building interactive components
|
|
11
|
-
- fixing accessibility defects
|
|
12
|
-
- writing semantic HTML
|
|
13
|
-
|
|
14
|
-
## Instructions
|
|
15
|
-
|
|
16
|
-
### Project Detection & Existing Rules
|
|
17
|
-
- **Inspect package.json & Configuration**: Check if the project uses specific accessibility linters (`eslint-plugin-jsx-a11y`) or UI component libraries (like Radix or Headless UI) that handle accessibility primitives.
|
|
18
|
-
- **Follow existing patterns**: Integrate with existing accessibility patterns in the project.
|
|
19
|
-
|
|
20
|
-
### Core Mental Model
|
|
21
|
-
- Accessibility means the interface remains usable across keyboard, screen readers, different input methods, visual abilities, cognitive contexts, and motion preferences.
|
|
22
|
-
- It is not merely "use semantic HTML"—it is about communicating state, identity, and behavior to all users.
|
|
23
|
-
|
|
24
|
-
## Rules
|
|
25
|
-
|
|
26
|
-
### Semantic HTML
|
|
27
|
-
Before adding ARIA:
|
|
28
|
-
- Ask whether native HTML already provides the correct semantics.
|
|
29
|
-
- Prefer native elements (`<button>`, `<nav>`, `<main>`) over recreating them with `<div>` and ARIA roles.
|
|
30
|
-
|
|
31
|
-
### Buttons vs Links
|
|
32
|
-
- Use **buttons** (`<button>`) for actions that change state or trigger behavior on the page.
|
|
33
|
-
- Use **links** (`<a>`) for navigation to new URLs or anchors.
|
|
34
|
-
- Do not create clickable divs when a native element exists.
|
|
35
|
-
|
|
36
|
-
### Keyboard
|
|
37
|
-
- Every interactive feature must have an intentional keyboard interaction.
|
|
38
|
-
- Check tab order (`tabindex="0"` for interactive elements only, avoid positive `tabindex`).
|
|
39
|
-
- Check activation (Space/Enter).
|
|
40
|
-
- Verify focus visibility.
|
|
41
|
-
- Prevent keyboard traps.
|
|
42
|
-
|
|
43
|
-
### Focus
|
|
44
|
-
Before removing outlines or focus indicators:
|
|
45
|
-
- Provide an equivalent, clearly visible focus state for keyboard users (`:focus-visible`).
|
|
46
|
-
|
|
47
|
-
### Forms
|
|
48
|
-
- Ensure inputs have associated labels (`<label for="...">` or `aria-labelledby`).
|
|
49
|
-
- Associate error messaging with inputs using `aria-describedby` or `aria-errormessage`.
|
|
50
|
-
- Provide useful validation messaging and indicate required state (`aria-required="true"` or `required` attribute).
|
|
51
|
-
|
|
52
|
-
### ARIA
|
|
53
|
-
- Use ARIA to communicate semantics that native HTML cannot express (e.g. `aria-expanded`, `aria-controls`).
|
|
54
|
-
- **Do not add redundant ARIA** (e.g. `<button role="button">`).
|
|
55
|
-
- **Do not use ARIA to repair incorrect markup** when simply changing to the correct native HTML tag solves the problem.
|
|
56
|
-
|
|
57
|
-
### Dynamic UI
|
|
58
|
-
- For dialogs, menus, popovers, and loading states: focus management must be intentional (e.g., trapping focus inside a modal, returning focus to the trigger on close).
|
|
59
|
-
- Use live regions (`aria-live`) for dynamic validation errors or status updates.
|
|
60
|
-
|
|
61
|
-
### Motion
|
|
62
|
-
- Respect `prefers-reduced-motion` media queries for animations.
|
|
63
|
-
- Do not make motion the only way information is communicated.
|
|
64
|
-
|
|
65
|
-
### Color
|
|
66
|
-
- Do not communicate meaning through color alone (e.g., use an icon or text alongside a red border for an error state).
|
|
67
|
-
- Ensure sufficient color contrast.
|
|
68
|
-
|
|
69
|
-
## Anti-Patterns
|
|
70
|
-
|
|
71
|
-
- **Clickable divs**
|
|
72
|
-
- *What*: `<div onClick={handleClick}>Submit</div>`.
|
|
73
|
-
- *Why*: Divs are not focusable by default and do not respond to Enter/Space keys, making them inaccessible to keyboard/screen reader users.
|
|
74
|
-
- *Instead*: Use a `<button>`.
|
|
75
|
-
- **Missing labels**
|
|
76
|
-
- *What*: `<input type="text" placeholder="Search" />` without a label.
|
|
77
|
-
- *Why*: Screen readers may not read the placeholder, leaving users blind to the input's purpose.
|
|
78
|
-
- *Instead*: Provide a visible `<label>` or `aria-label`.
|
|
79
|
-
- **Invisible focus**
|
|
80
|
-
- *What*: `outline: none;` without providing a replacement `:focus` or `:focus-visible` style.
|
|
81
|
-
- *Why*: Keyboard users lose track of where they are on the page.
|
|
82
|
-
- *Instead*: Keep the default outline or provide a high-contrast custom focus ring.
|
|
83
|
-
- **Unnecessary ARIA**
|
|
84
|
-
- *What*: Adding `role="navigation"` to a `<nav>` element.
|
|
85
|
-
- *Why*: It is redundant and adds noise for screen readers.
|
|
86
|
-
- *Instead*: Just use `<nav>`.
|
|
87
|
-
|
|
88
|
-
## Workflow
|
|
89
|
-
|
|
90
|
-
### Debugging
|
|
91
|
-
- Determine if the issue is a missing semantic element, missing keyboard support, or incorrect ARIA state.
|
|
92
|
-
- Inspect the Accessibility Tree in the browser (if available).
|
|
93
|
-
|
|
94
|
-
### Verification
|
|
95
|
-
- Verify keyboard navigation manually or via tests.
|
|
96
|
-
- Inspect semantic markup.
|
|
97
|
-
- Run automated accessibility checks (`eslint-plugin-jsx-a11y`, `axe-core`) where available in the project.
|
|
98
|
-
- Do not claim automated accessibility verification succeeded unless a real tool was executed.
|
|
1
|
+
---
|
|
2
|
+
name: accessibility
|
|
3
|
+
description: Practical web accessibility implementation, ARIA semantics, keyboard navigation, and focus management.
|
|
4
|
+
category: accessibility
|
|
5
|
+
version: 2.1.0
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## When to use
|
|
9
|
+
|
|
10
|
+
- building interactive components
|
|
11
|
+
- fixing accessibility defects
|
|
12
|
+
- writing semantic HTML
|
|
13
|
+
|
|
14
|
+
## Instructions
|
|
15
|
+
|
|
16
|
+
### Project Detection & Existing Rules
|
|
17
|
+
- **Inspect package.json & Configuration**: Check if the project uses specific accessibility linters (`eslint-plugin-jsx-a11y`) or UI component libraries (like Radix or Headless UI) that handle accessibility primitives.
|
|
18
|
+
- **Follow existing patterns**: Integrate with existing accessibility patterns in the project.
|
|
19
|
+
|
|
20
|
+
### Core Mental Model
|
|
21
|
+
- Accessibility means the interface remains usable across keyboard, screen readers, different input methods, visual abilities, cognitive contexts, and motion preferences.
|
|
22
|
+
- It is not merely "use semantic HTML"—it is about communicating state, identity, and behavior to all users.
|
|
23
|
+
|
|
24
|
+
## Rules
|
|
25
|
+
|
|
26
|
+
### Semantic HTML
|
|
27
|
+
Before adding ARIA:
|
|
28
|
+
- Ask whether native HTML already provides the correct semantics.
|
|
29
|
+
- Prefer native elements (`<button>`, `<nav>`, `<main>`) over recreating them with `<div>` and ARIA roles.
|
|
30
|
+
|
|
31
|
+
### Buttons vs Links
|
|
32
|
+
- Use **buttons** (`<button>`) for actions that change state or trigger behavior on the page.
|
|
33
|
+
- Use **links** (`<a>`) for navigation to new URLs or anchors.
|
|
34
|
+
- Do not create clickable divs when a native element exists.
|
|
35
|
+
|
|
36
|
+
### Keyboard
|
|
37
|
+
- Every interactive feature must have an intentional keyboard interaction.
|
|
38
|
+
- Check tab order (`tabindex="0"` for interactive elements only, avoid positive `tabindex`).
|
|
39
|
+
- Check activation (Space/Enter).
|
|
40
|
+
- Verify focus visibility.
|
|
41
|
+
- Prevent keyboard traps.
|
|
42
|
+
|
|
43
|
+
### Focus
|
|
44
|
+
Before removing outlines or focus indicators:
|
|
45
|
+
- Provide an equivalent, clearly visible focus state for keyboard users (`:focus-visible`).
|
|
46
|
+
|
|
47
|
+
### Forms
|
|
48
|
+
- Ensure inputs have associated labels (`<label for="...">` or `aria-labelledby`).
|
|
49
|
+
- Associate error messaging with inputs using `aria-describedby` or `aria-errormessage`.
|
|
50
|
+
- Provide useful validation messaging and indicate required state (`aria-required="true"` or `required` attribute).
|
|
51
|
+
|
|
52
|
+
### ARIA
|
|
53
|
+
- Use ARIA to communicate semantics that native HTML cannot express (e.g. `aria-expanded`, `aria-controls`).
|
|
54
|
+
- **Do not add redundant ARIA** (e.g. `<button role="button">`).
|
|
55
|
+
- **Do not use ARIA to repair incorrect markup** when simply changing to the correct native HTML tag solves the problem.
|
|
56
|
+
|
|
57
|
+
### Dynamic UI
|
|
58
|
+
- For dialogs, menus, popovers, and loading states: focus management must be intentional (e.g., trapping focus inside a modal, returning focus to the trigger on close).
|
|
59
|
+
- Use live regions (`aria-live`) for dynamic validation errors or status updates.
|
|
60
|
+
|
|
61
|
+
### Motion
|
|
62
|
+
- Respect `prefers-reduced-motion` media queries for animations.
|
|
63
|
+
- Do not make motion the only way information is communicated.
|
|
64
|
+
|
|
65
|
+
### Color
|
|
66
|
+
- Do not communicate meaning through color alone (e.g., use an icon or text alongside a red border for an error state).
|
|
67
|
+
- Ensure sufficient color contrast.
|
|
68
|
+
|
|
69
|
+
## Anti-Patterns
|
|
70
|
+
|
|
71
|
+
- **Clickable divs**
|
|
72
|
+
- *What*: `<div onClick={handleClick}>Submit</div>`.
|
|
73
|
+
- *Why*: Divs are not focusable by default and do not respond to Enter/Space keys, making them inaccessible to keyboard/screen reader users.
|
|
74
|
+
- *Instead*: Use a `<button>`.
|
|
75
|
+
- **Missing labels**
|
|
76
|
+
- *What*: `<input type="text" placeholder="Search" />` without a label.
|
|
77
|
+
- *Why*: Screen readers may not read the placeholder, leaving users blind to the input's purpose.
|
|
78
|
+
- *Instead*: Provide a visible `<label>` or `aria-label`.
|
|
79
|
+
- **Invisible focus**
|
|
80
|
+
- *What*: `outline: none;` without providing a replacement `:focus` or `:focus-visible` style.
|
|
81
|
+
- *Why*: Keyboard users lose track of where they are on the page.
|
|
82
|
+
- *Instead*: Keep the default outline or provide a high-contrast custom focus ring.
|
|
83
|
+
- **Unnecessary ARIA**
|
|
84
|
+
- *What*: Adding `role="navigation"` to a `<nav>` element.
|
|
85
|
+
- *Why*: It is redundant and adds noise for screen readers.
|
|
86
|
+
- *Instead*: Just use `<nav>`.
|
|
87
|
+
|
|
88
|
+
## Workflow
|
|
89
|
+
|
|
90
|
+
### Debugging
|
|
91
|
+
- Determine if the issue is a missing semantic element, missing keyboard support, or incorrect ARIA state.
|
|
92
|
+
- Inspect the Accessibility Tree in the browser (if available).
|
|
93
|
+
|
|
94
|
+
### Verification
|
|
95
|
+
- Verify keyboard navigation manually or via tests.
|
|
96
|
+
- Inspect semantic markup.
|
|
97
|
+
- Run automated accessibility checks (`eslint-plugin-jsx-a11y`, `axe-core`) where available in the project.
|
|
98
|
+
- Do not claim automated accessibility verification succeeded unless a real tool was executed.
|
package/skills/css/SKILL.md
CHANGED
|
@@ -1,90 +1,90 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: css
|
|
3
|
-
description: Cascading Style Sheets architecture, layout, specificty, and modern responsive mechanics.
|
|
4
|
-
category: styling
|
|
5
|
-
version: 2.1.0
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
## When to use
|
|
9
|
-
|
|
10
|
-
- writing CSS
|
|
11
|
-
- modifying layouts
|
|
12
|
-
- resolving visual defects
|
|
13
|
-
|
|
14
|
-
## Instructions
|
|
15
|
-
|
|
16
|
-
### Project Detection & Existing Rules
|
|
17
|
-
- **Inspect package.json & Stylesheets**: Determine if the project uses plain CSS, CSS Modules, Sass/Less, or utility frameworks (e.g. Tailwind).
|
|
18
|
-
- **Follow existing patterns**: Do not introduce a styling architecture that the project does not use (like dropping in Tailwind classes into a CSS Modules project).
|
|
19
|
-
- **Respect naming conventions**: Use existing class naming conventions (e.g. BEM).
|
|
20
|
-
|
|
21
|
-
### Core Mental Model
|
|
22
|
-
- **Cascade & Inheritance**: Rules apply based on cascade origin, specificity, and source order. Properties like color and font inherit, while layout properties do not.
|
|
23
|
-
- **Specificity**: Browsers calculate selector weight. Inline > ID > Class/Attribute/Pseudo-class > Element/Pseudo-element.
|
|
24
|
-
- **Source Order**: Later rules win when specificity is equal.
|
|
25
|
-
- **Box Model**: Elements have content, padding, border, and margin. Use `box-sizing: border-box`.
|
|
26
|
-
- **Containing Blocks**: Absolute positioning is relative to the nearest positioned ancestor.
|
|
27
|
-
- **Layout vs Decoration**: Separate properties that affect document flow (flex, grid, width) from decorative properties (color, background).
|
|
28
|
-
|
|
29
|
-
## Rules
|
|
30
|
-
|
|
31
|
-
### Layout
|
|
32
|
-
Before using `position: absolute`:
|
|
33
|
-
- Ask whether normal document flow, flexbox, or CSS grid solves the layout more robustly.
|
|
34
|
-
|
|
35
|
-
### Flexbox vs Grid
|
|
36
|
-
- **Flexbox**: Use for 1-dimensional layouts (a row or a column) where content dictates the size.
|
|
37
|
-
- **Grid**: Use for 2-dimensional layouts where the structural grid dictates the layout.
|
|
38
|
-
|
|
39
|
-
### Fixed vs Fluid
|
|
40
|
-
- Prefer fluid constraints (`%`, `vw`, `vh`, `fr`) when content and viewport can vary.
|
|
41
|
-
- Avoid rigid fixed widths (`width: 500px`) that will break on mobile devices.
|
|
42
|
-
|
|
43
|
-
### z-index
|
|
44
|
-
Before increasing `z-index`:
|
|
45
|
-
- Inspect stacking contexts. A high `z-index` inside a lower stacking context will not overlay elements in a higher stacking context.
|
|
46
|
-
- Do not solve every layering problem by setting a huge `z-index` (e.g. `z-index: 9999`).
|
|
47
|
-
|
|
48
|
-
### Specificity
|
|
49
|
-
Before adding `!important`:
|
|
50
|
-
- Determine which selector or cascade rule is causing the conflict.
|
|
51
|
-
- Avoid specificity escalation by refactoring the selector to match the target's specificity organically.
|
|
52
|
-
|
|
53
|
-
### Responsive CSS
|
|
54
|
-
- Prefer content-driven breakpoints over excessive device-specific media queries.
|
|
55
|
-
|
|
56
|
-
### Modern CSS
|
|
57
|
-
- Use custom properties (CSS variables), `clamp()`, `min()`, `max()`, container queries, logical properties, and modern color functions where appropriate.
|
|
58
|
-
- **Browser Support**: Do not force modern features when the project's browser support does not allow them. Check existing CSS files for compatibility clues.
|
|
59
|
-
|
|
60
|
-
## Anti-Patterns
|
|
61
|
-
|
|
62
|
-
- **!important everywhere**
|
|
63
|
-
- *What*: Slapping `!important` on properties that don't apply or just to win a specificity war.
|
|
64
|
-
- *Why*: It breaks the cascade and makes future maintenance a nightmare of specificity wars.
|
|
65
|
-
- *Instead*: Find the conflicting rule and match or slightly exceed its specificity organically.
|
|
66
|
-
- **Arbitrary z-index escalation**
|
|
67
|
-
- *What*: Using `z-index: 99999`.
|
|
68
|
-
- *Why*: It leads to unpredictable layering and arms races between components.
|
|
69
|
-
- *Instead*: Manage stacking contexts carefully and use a sensible, planned z-index scale.
|
|
70
|
-
- **Fixed widths for fluid content**
|
|
71
|
-
- *What*: Setting `width: 800px` on a container.
|
|
72
|
-
- *Why*: It causes horizontal scrolling or cropping on narrow viewports.
|
|
73
|
-
- *Instead*: Use `max-width: 800px; width: 100%`.
|
|
74
|
-
- **Deeply nested selectors**
|
|
75
|
-
- *What*: Writing `.card .body .title span { ... }`.
|
|
76
|
-
- *Why*: It inflates specificity, making it very hard to override styles later.
|
|
77
|
-
- *Instead*: Use flatter selector structures (e.g., BEM `.card__title`).
|
|
78
|
-
|
|
79
|
-
## Workflow
|
|
80
|
-
|
|
81
|
-
### Debugging
|
|
82
|
-
- Inspect computed styles in the browser (if available) to see which rules are winning.
|
|
83
|
-
- Check the box model (padding, border, margin) to understand element sizing.
|
|
84
|
-
- Inspect layout dimensions, parent constraints, and overflow settings.
|
|
85
|
-
- Verify stacking contexts when diagnosing z-index issues.
|
|
86
|
-
- Do not claim browser inspection is available unless a browser tool is actively being used.
|
|
87
|
-
|
|
88
|
-
### Verification
|
|
89
|
-
- Ensure the layout responds correctly across narrow and wide simulated viewports.
|
|
90
|
-
- Run project CSS linting (e.g. Stylelint) and build steps to verify syntax.
|
|
1
|
+
---
|
|
2
|
+
name: css
|
|
3
|
+
description: Cascading Style Sheets architecture, layout, specificty, and modern responsive mechanics.
|
|
4
|
+
category: styling
|
|
5
|
+
version: 2.1.0
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## When to use
|
|
9
|
+
|
|
10
|
+
- writing CSS
|
|
11
|
+
- modifying layouts
|
|
12
|
+
- resolving visual defects
|
|
13
|
+
|
|
14
|
+
## Instructions
|
|
15
|
+
|
|
16
|
+
### Project Detection & Existing Rules
|
|
17
|
+
- **Inspect package.json & Stylesheets**: Determine if the project uses plain CSS, CSS Modules, Sass/Less, or utility frameworks (e.g. Tailwind).
|
|
18
|
+
- **Follow existing patterns**: Do not introduce a styling architecture that the project does not use (like dropping in Tailwind classes into a CSS Modules project).
|
|
19
|
+
- **Respect naming conventions**: Use existing class naming conventions (e.g. BEM).
|
|
20
|
+
|
|
21
|
+
### Core Mental Model
|
|
22
|
+
- **Cascade & Inheritance**: Rules apply based on cascade origin, specificity, and source order. Properties like color and font inherit, while layout properties do not.
|
|
23
|
+
- **Specificity**: Browsers calculate selector weight. Inline > ID > Class/Attribute/Pseudo-class > Element/Pseudo-element.
|
|
24
|
+
- **Source Order**: Later rules win when specificity is equal.
|
|
25
|
+
- **Box Model**: Elements have content, padding, border, and margin. Use `box-sizing: border-box`.
|
|
26
|
+
- **Containing Blocks**: Absolute positioning is relative to the nearest positioned ancestor.
|
|
27
|
+
- **Layout vs Decoration**: Separate properties that affect document flow (flex, grid, width) from decorative properties (color, background).
|
|
28
|
+
|
|
29
|
+
## Rules
|
|
30
|
+
|
|
31
|
+
### Layout
|
|
32
|
+
Before using `position: absolute`:
|
|
33
|
+
- Ask whether normal document flow, flexbox, or CSS grid solves the layout more robustly.
|
|
34
|
+
|
|
35
|
+
### Flexbox vs Grid
|
|
36
|
+
- **Flexbox**: Use for 1-dimensional layouts (a row or a column) where content dictates the size.
|
|
37
|
+
- **Grid**: Use for 2-dimensional layouts where the structural grid dictates the layout.
|
|
38
|
+
|
|
39
|
+
### Fixed vs Fluid
|
|
40
|
+
- Prefer fluid constraints (`%`, `vw`, `vh`, `fr`) when content and viewport can vary.
|
|
41
|
+
- Avoid rigid fixed widths (`width: 500px`) that will break on mobile devices.
|
|
42
|
+
|
|
43
|
+
### z-index
|
|
44
|
+
Before increasing `z-index`:
|
|
45
|
+
- Inspect stacking contexts. A high `z-index` inside a lower stacking context will not overlay elements in a higher stacking context.
|
|
46
|
+
- Do not solve every layering problem by setting a huge `z-index` (e.g. `z-index: 9999`).
|
|
47
|
+
|
|
48
|
+
### Specificity
|
|
49
|
+
Before adding `!important`:
|
|
50
|
+
- Determine which selector or cascade rule is causing the conflict.
|
|
51
|
+
- Avoid specificity escalation by refactoring the selector to match the target's specificity organically.
|
|
52
|
+
|
|
53
|
+
### Responsive CSS
|
|
54
|
+
- Prefer content-driven breakpoints over excessive device-specific media queries.
|
|
55
|
+
|
|
56
|
+
### Modern CSS
|
|
57
|
+
- Use custom properties (CSS variables), `clamp()`, `min()`, `max()`, container queries, logical properties, and modern color functions where appropriate.
|
|
58
|
+
- **Browser Support**: Do not force modern features when the project's browser support does not allow them. Check existing CSS files for compatibility clues.
|
|
59
|
+
|
|
60
|
+
## Anti-Patterns
|
|
61
|
+
|
|
62
|
+
- **!important everywhere**
|
|
63
|
+
- *What*: Slapping `!important` on properties that don't apply or just to win a specificity war.
|
|
64
|
+
- *Why*: It breaks the cascade and makes future maintenance a nightmare of specificity wars.
|
|
65
|
+
- *Instead*: Find the conflicting rule and match or slightly exceed its specificity organically.
|
|
66
|
+
- **Arbitrary z-index escalation**
|
|
67
|
+
- *What*: Using `z-index: 99999`.
|
|
68
|
+
- *Why*: It leads to unpredictable layering and arms races between components.
|
|
69
|
+
- *Instead*: Manage stacking contexts carefully and use a sensible, planned z-index scale.
|
|
70
|
+
- **Fixed widths for fluid content**
|
|
71
|
+
- *What*: Setting `width: 800px` on a container.
|
|
72
|
+
- *Why*: It causes horizontal scrolling or cropping on narrow viewports.
|
|
73
|
+
- *Instead*: Use `max-width: 800px; width: 100%`.
|
|
74
|
+
- **Deeply nested selectors**
|
|
75
|
+
- *What*: Writing `.card .body .title span { ... }`.
|
|
76
|
+
- *Why*: It inflates specificity, making it very hard to override styles later.
|
|
77
|
+
- *Instead*: Use flatter selector structures (e.g., BEM `.card__title`).
|
|
78
|
+
|
|
79
|
+
## Workflow
|
|
80
|
+
|
|
81
|
+
### Debugging
|
|
82
|
+
- Inspect computed styles in the browser (if available) to see which rules are winning.
|
|
83
|
+
- Check the box model (padding, border, margin) to understand element sizing.
|
|
84
|
+
- Inspect layout dimensions, parent constraints, and overflow settings.
|
|
85
|
+
- Verify stacking contexts when diagnosing z-index issues.
|
|
86
|
+
- Do not claim browser inspection is available unless a browser tool is actively being used.
|
|
87
|
+
|
|
88
|
+
### Verification
|
|
89
|
+
- Ensure the layout responds correctly across narrow and wide simulated viewports.
|
|
90
|
+
- Run project CSS linting (e.g. Stylelint) and build steps to verify syntax.
|