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.
Files changed (98) hide show
  1. package/README.md +92 -8
  2. package/dist/index.js +23293 -1
  3. package/dist/{node.browser-BsGbhAIw.js → node.browser-2EgZAKSy.js} +1 -1
  4. package/dist/{node.browser-B5CfqNxN.js → node.browser-B5Gur0wd.js} +1 -1
  5. package/dist/{node.browser-BWLpZywP.js → node.browser-BSlAsiSV.js} +1 -1
  6. package/dist/{node.browser-7pW7d9_e.js → node.browser-CdVAMgSg.js} +1 -1
  7. package/dist/{src-CxriUNOE.js → src-CSWdjU4j.js} +4836 -4522
  8. package/dist/{src-DBoGZaxi.js → src-DY3OmBmT.js} +6670 -4557
  9. package/dist/{src-B_Z8CdqT.js → src-DcYf8vsK.js} +4850 -4526
  10. package/dist/{src-Bhec3XmL.js → src-DkWmcv2Q.js} +6677 -4604
  11. package/package.json +5 -2
  12. package/skills/accessibility/SKILL.md +98 -98
  13. package/skills/css/SKILL.md +90 -90
  14. package/skills/frontend-debugging/SKILL.md +201 -201
  15. package/skills/frontend-design/SKILL.md +358 -358
  16. package/skills/frontend-performance/SKILL.md +89 -89
  17. package/skills/frontend-testing/SKILL.md +87 -87
  18. package/skills/nextjs/SKILL.md +75 -75
  19. package/skills/react/SKILL.md +213 -213
  20. package/skills/responsive-design/SKILL.md +190 -190
  21. package/skills/svelte/SKILL.md +86 -86
  22. package/skills/tailwind/SKILL.md +74 -74
  23. package/skills/ui-review/SKILL.md +245 -245
  24. package/skills/vue/SKILL.md +72 -72
  25. package/dist/App.d.ts +0 -33
  26. package/dist/App.js +0 -2224
  27. package/dist/approvalResolver.d.ts +0 -12
  28. package/dist/approvalResolver.js +0 -112
  29. package/dist/commands.d.ts +0 -11
  30. package/dist/commands.js +0 -33
  31. package/dist/error-qAR8Lv-R.js +0 -57
  32. package/dist/index.d.ts +0 -3
  33. package/dist/node.browser-C9Wg-Fje.js +0 -46
  34. package/dist/node.browser-CADgAblr.js +0 -46
  35. package/dist/node.browser-Cse19Rko.js +0 -47
  36. package/dist/node.browser-Cx8sZi1Z.js +0 -46
  37. package/dist/node.browser-DtPNhPGQ.js +0 -46
  38. package/dist/node.browser-DvjMZMaq.js +0 -46
  39. package/dist/node.browser-EewJmuUw.js +0 -46
  40. package/dist/node.browser-J7voHtuR.js +0 -10
  41. package/dist/src-4fKRO0jn.js +0 -31655
  42. package/dist/src-8kA-5Kbs.js +0 -31591
  43. package/dist/src-C8Oe06wn.js +0 -31580
  44. package/dist/src-D78uLcuc.js +0 -31573
  45. package/dist/src-EyWDnffN.js +0 -31636
  46. package/dist/src-dhvwrHAJ.js +0 -31590
  47. package/dist/ui/AppShell.d.ts +0 -14
  48. package/dist/ui/AppShell.js +0 -25
  49. package/dist/ui/ApprovalPrompt.d.ts +0 -31
  50. package/dist/ui/ApprovalPrompt.js +0 -55
  51. package/dist/ui/BlockedView.d.ts +0 -13
  52. package/dist/ui/BlockedView.js +0 -7
  53. package/dist/ui/CommandPalette.d.ts +0 -8
  54. package/dist/ui/CommandPalette.js +0 -18
  55. package/dist/ui/CurrentStepView.d.ts +0 -16
  56. package/dist/ui/CurrentStepView.js +0 -28
  57. package/dist/ui/DiagnosticsView.d.ts +0 -45
  58. package/dist/ui/DiagnosticsView.js +0 -23
  59. package/dist/ui/ExecutionTimeline.d.ts +0 -15
  60. package/dist/ui/ExecutionTimeline.js +0 -51
  61. package/dist/ui/ExecutionView.d.ts +0 -42
  62. package/dist/ui/ExecutionView.js +0 -20
  63. package/dist/ui/Header.d.ts +0 -15
  64. package/dist/ui/Header.js +0 -47
  65. package/dist/ui/HelpView.d.ts +0 -3
  66. package/dist/ui/HelpView.js +0 -35
  67. package/dist/ui/MessageBubble.d.ts +0 -9
  68. package/dist/ui/MessageBubble.js +0 -58
  69. package/dist/ui/PlanStep.d.ts +0 -16
  70. package/dist/ui/PlanStep.js +0 -71
  71. package/dist/ui/PlanView.d.ts +0 -26
  72. package/dist/ui/PlanView.js +0 -24
  73. package/dist/ui/ProgressBar.d.ts +0 -10
  74. package/dist/ui/ProgressBar.js +0 -14
  75. package/dist/ui/RecoveryView.d.ts +0 -20
  76. package/dist/ui/RecoveryView.js +0 -19
  77. package/dist/ui/ReplanView.d.ts +0 -16
  78. package/dist/ui/ReplanView.js +0 -21
  79. package/dist/ui/ResumeView.d.ts +0 -15
  80. package/dist/ui/ResumeView.js +0 -25
  81. package/dist/ui/RiskNotice.d.ts +0 -10
  82. package/dist/ui/RiskNotice.js +0 -21
  83. package/dist/ui/RunHistoryView.d.ts +0 -15
  84. package/dist/ui/RunHistoryView.js +0 -39
  85. package/dist/ui/StatusBar.d.ts +0 -16
  86. package/dist/ui/StatusBar.js +0 -104
  87. package/dist/ui/TaskInput.d.ts +0 -15
  88. package/dist/ui/TaskInput.js +0 -8
  89. package/dist/ui/ThinkingBlock.d.ts +0 -8
  90. package/dist/ui/ThinkingBlock.js +0 -13
  91. package/dist/ui/ThinkingIndicator.d.ts +0 -7
  92. package/dist/ui/ThinkingIndicator.js +0 -20
  93. package/dist/ui/TurnView.d.ts +0 -13
  94. package/dist/ui/TurnView.js +0 -11
  95. package/dist/ui/WorkspaceStatus.d.ts +0 -20
  96. package/dist/ui/WorkspaceStatus.js +0 -23
  97. package/dist/ui/index.d.ts +0 -26
  98. 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.1.3",
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": "^4.77.0",
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.
@@ -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.