@mytechtoday/augment-extensions 0.7.0 → 1.2.0

package/augment-extensions/coding-standards/css/rules/css-standards.md

@@ -1,492 +1,492 @@
-# CSS Standards
-
-## Overview
-
-This guide provides CSS standards covering naming conventions, organization, selectors, and responsive design for maintainable and scalable stylesheets.
-
----
-
-## Naming Conventions
-
-### Kebab-Case for Class Names
-
-**REQUIRED**: Use kebab-case for all class names:
-
-```css
-/* ✅ GOOD */
-.user-profile { }
-.nav-menu-item { }
-.btn-primary { }
-
-/* ❌ BAD */
-.userProfile { }  /* camelCase */
-.user_profile { } /* snake_case */
-.UserProfile { }  /* PascalCase */
-```
-
-### BEM (Block Element Modifier)
-
-**RECOMMENDED**: Use BEM for component-based naming:
-
-```css
-/* Block */
-.card { }
-
-/* Element (part of block) */
-.card__header { }
-.card__body { }
-.card__footer { }
-
-/* Modifier (variation of block or element) */
-.card--featured { }
-.card__header--large { }
-```
-
-**Example**:
-
-```html
-<div class="card card--featured">
-  <div class="card__header card__header--large">
-    <h2 class="card__title">Title</h2>
-  </div>
-  <div class="card__body">
-    <p>Content</p>
-  </div>
-</div>
-```
-
-### Descriptive and Semantic Names
-
-**DO** use descriptive, semantic class names:
-
-```css
-/* ✅ GOOD: Describes purpose */
-.primary-navigation { }
-.user-avatar { }
-.error-message { }
-
-/* ❌ BAD: Describes appearance */
-.red-text { }
-.big-box { }
-.left-column { }
-```
-
-### Avoid IDs for Styling
-
-**RECOMMENDED**: Use IDs for JavaScript hooks only, not styling:
-
-```css
-/* ✅ GOOD */
-.header { }
-
-/* ❌ BAD */
-#header { }
-```
-
-**REASON**: IDs have high specificity and are harder to override.
-
----
-
-## CSS Organization
-
-### Component-Based Organization
-
-**RECOMMENDED**: Organize CSS by component or feature:
-
-```
-styles/
-├── base/
-│   ├── reset.css
-│   ├── typography.css
-│   └── variables.css
-├── components/
-│   ├── button.css
-│   ├── card.css
-│   └── navigation.css
-├── layouts/
-│   ├── grid.css
-│   └── header.css
-└── utilities/
-    └── spacing.css
-```
-
-### Separate Global and Component Styles
-
-```css
-/* global.css - Global styles */
-:root {
-  --color-primary: #007bff;
-  --spacing-unit: 8px;
-}
-
-* {
-  box-sizing: border-box;
-}
-
-/* button.css - Component styles */
-.btn {
-  padding: var(--spacing-unit);
-  background: var(--color-primary);
-}
-```
-
-### CSS Custom Properties (Variables)
-
-**RECOMMENDED**: Use CSS custom properties for theming:
-
-```css
-/* ✅ GOOD: Define at :root */
-:root {
-  --color-primary: #007bff;
-  --color-secondary: #6c757d;
-  --font-family-base: 'Helvetica Neue', sans-serif;
-  --spacing-sm: 8px;
-  --spacing-md: 16px;
-  --spacing-lg: 24px;
-}
-
-.btn {
-  background: var(--color-primary);
-  padding: var(--spacing-md);
-  font-family: var(--font-family-base);
-}
-
-/* Provide fallbacks */
-.btn {
-  background: var(--color-primary, #007bff);
-}
-```
-
-### Avoid @import
-
-**DON'T** use `@import` in CSS (use build tools instead):
-
-```css
-/* ❌ BAD: Blocks rendering */
-@import url('typography.css');
-
-/* ✅ GOOD: Use build tools or multiple <link> tags */
-```
-
-**REASON**: `@import` blocks parallel downloads and slows page load.
-
----
-
-## CSS Selectors
-
-### Keep Specificity Low
-
-**DO** keep specificity as low as possible:
-
-```css
-/* ✅ GOOD: Low specificity */
-.nav-item { }
-.nav-item.active { }
-
-/* ❌ BAD: High specificity */
-nav ul li a.nav-item { }
-#header .nav ul li a { }
-```
-
-### Limit Nesting
-
-**RECOMMENDED**: Limit nesting to 3 levels maximum:
-
-```css
-/* ✅ GOOD: Shallow nesting */
-.card { }
-.card__header { }
-.card__title { }
-
-/* ❌ BAD: Deep nesting */
-.card .card__header .card__title span.text { }
-```
-
-### Avoid Universal Selector
-
-**USE SPARINGLY**: Universal selector (`*`) can impact performance:
-
-```css
-/* ✅ ACCEPTABLE: Box-sizing reset */
-* {
-  box-sizing: border-box;
-}
-
-/* ❌ BAD: Overly broad */
-* {
-  margin: 0;
-  padding: 0;
-}
-```
-
-### Avoid !important
-
-**AVOID**: Use `!important` only for utilities:
-
-```css
-/* ✅ ACCEPTABLE: Utility class */
-.hidden {
-  display: none !important;
-}
-
-/* ❌ BAD: Regular styling */
-.btn {
-  background: blue !important;
-}
-```
-
----
-
-## Responsive Design
-
-### Mobile-First Approach
-
-**RECOMMENDED**: Start with mobile styles, add complexity for larger screens:
-
-```css
-/* ✅ GOOD: Mobile-first */
-.container {
-  padding: 16px;
-}
-
-@media (min-width: 768px) {
-  .container {
-    padding: 24px;
-  }
-}
-
-@media (min-width: 1024px) {
-  .container {
-    padding: 32px;
-  }
-}
-
-/* ❌ BAD: Desktop-first */
-.container {
-  padding: 32px;
-}
-
-@media (max-width: 1024px) {
-  .container {
-    padding: 24px;
-  }
-}
-```
-
-### Media Query Units
-
-**RECOMMENDED**: Use `em` or `rem` units for media queries:
-
-```css
-/* ✅ GOOD: em-based (more accessible) */
-@media (min-width: 48em) { /* 768px at 16px base */ }
-@media (min-width: 64em) { /* 1024px at 16px base */ }
-
-/* ❌ ACCEPTABLE: px-based (less flexible) */
-@media (min-width: 768px) { }
-```
-
-### Consistent Breakpoints
-
-**RECOMMENDED**: Define consistent breakpoints:
-
-```css
-:root {
-  --breakpoint-sm: 36em;   /* 576px */
-  --breakpoint-md: 48em;   /* 768px */
-  --breakpoint-lg: 64em;   /* 1024px */
-  --breakpoint-xl: 80em;   /* 1280px */
-}
-
-/* Use in media queries */
-@media (min-width: 48em) { /* md */ }
-@media (min-width: 64em) { /* lg */ }
-```
-
-### CSS Grid and Flexbox
-
-**RECOMMENDED**: Prefer Grid and Flexbox over floats:
-
-```css
-/* ✅ GOOD: Flexbox for 1D layouts */
-.nav {
-  display: flex;
-  gap: 16px;
-  align-items: center;
-}
-
-/* ✅ GOOD: Grid for 2D layouts */
-.gallery {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
-  gap: 16px;
-}
-
-/* ❌ BAD: Floats (legacy) */
-.column {
-  float: left;
-  width: 50%;
-}
-```
-
----
-
-## Code Quality
-
-### Formatting
-
-**RECOMMENDED**: Use consistent formatting:
-
-```css
-/* ✅ GOOD: Consistent formatting */
-.selector {
-  property: value;
-  another-property: value;
-}
-
-.another-selector,
-.multiple-selector {
-  property: value;
-}
-
-/* Use Prettier or Stylelint for automatic formatting */
-```
-
-### Comments
-
-**RECOMMENDED**: Add comments for complex or non-obvious code:
-
-```css
-/* Component: Card
-   Usage: Product listings, blog posts
-   ========================================== */
-.card {
-  /* Prevent content overflow */
-  overflow: hidden;
-}
-
-/* TODO: Refactor to use CSS Grid */
-.legacy-layout {
-  float: left;
-}
-```
-
-### Property Order
-
-**RECOMMENDED**: Group related properties:
-
-```css
-.element {
-  /* Positioning */
-  position: relative;
-  top: 0;
-  left: 0;
-
-  /* Display & Box Model */
-  display: flex;
-  width: 100%;
-  padding: 16px;
-  margin: 0;
-
-  /* Typography */
-  font-size: 16px;
-  line-height: 1.5;
-
-  /* Visual */
-  background: white;
-  border: 1px solid gray;
-
-  /* Misc */
-  cursor: pointer;
-}
-```
-
----
-
-## Best Practices
-
-### Reset or Normalize
-
-**RECOMMENDED**: Use a CSS reset or normalize:
-
-```css
-/* Option 1: Simple reset */
-* {
-  margin: 0;
-  padding: 0;
-  box-sizing: border-box;
-}
-
-/* Option 2: Use normalize.css or modern-normalize */
-```
-
-### Avoid Inline Styles
-
-**DON'T** use inline styles (use classes instead):
-
-```html
-<!-- ❌ BAD -->
-<div style="color: red; font-size: 16px;">Text</div>
-
-<!-- ✅ GOOD -->
-<div class="error-text">Text</div>
-```
-
-### Use Shorthand Properties
-
-**RECOMMENDED**: Use shorthand when appropriate:
-
-```css
-/* ✅ GOOD: Shorthand */
-.element {
-  margin: 10px 20px;
-  padding: 10px;
-  background: white url('bg.png') no-repeat center;
-}
-
-/* ❌ VERBOSE: Longhand */
-.element {
-  margin-top: 10px;
-  margin-right: 20px;
-  margin-bottom: 10px;
-  margin-left: 20px;
-}
-```
-
-### Vendor Prefixes
-
-**RECOMMENDED**: Use autoprefixer instead of manual prefixes:
-
-```css
-/* ✅ GOOD: Let autoprefixer handle it */
-.element {
-  display: flex;
-  user-select: none;
-}
-
-/* ❌ BAD: Manual prefixes */
-.element {
-  display: -webkit-flex;
-  display: flex;
-  -webkit-user-select: none;
-  user-select: none;
-}
-```
-
----
-
-## Summary
-
-**Key Principles**:
-1. Use kebab-case for class names
-2. Consider BEM for component naming
-3. Keep specificity low
-4. Limit nesting to 3 levels
-5. Use mobile-first responsive design
-6. Prefer Grid/Flexbox over floats
-7. Use CSS custom properties for theming
-8. Avoid `!important` except for utilities
-9. Use Stylelint for code quality
-
-
-
+# CSS Standards
+
+## Overview
+
+This guide provides CSS standards covering naming conventions, organization, selectors, and responsive design for maintainable and scalable stylesheets.
+
+---
+
+## Naming Conventions
+
+### Kebab-Case for Class Names
+
+**REQUIRED**: Use kebab-case for all class names:
+
+```css
+/* ✅ GOOD */
+.user-profile { }
+.nav-menu-item { }
+.btn-primary { }
+
+/* ❌ BAD */
+.userProfile { }  /* camelCase */
+.user_profile { } /* snake_case */
+.UserProfile { }  /* PascalCase */
+```
+
+### BEM (Block Element Modifier)
+
+**RECOMMENDED**: Use BEM for component-based naming:
+
+```css
+/* Block */
+.card { }
+
+/* Element (part of block) */
+.card__header { }
+.card__body { }
+.card__footer { }
+
+/* Modifier (variation of block or element) */
+.card--featured { }
+.card__header--large { }
+```
+
+**Example**:
+
+```html
+<div class="card card--featured">
+  <div class="card__header card__header--large">
+    <h2 class="card__title">Title</h2>
+  </div>
+  <div class="card__body">
+    <p>Content</p>
+  </div>
+</div>
+```
+
+### Descriptive and Semantic Names
+
+**DO** use descriptive, semantic class names:
+
+```css
+/* ✅ GOOD: Describes purpose */
+.primary-navigation { }
+.user-avatar { }
+.error-message { }
+
+/* ❌ BAD: Describes appearance */
+.red-text { }
+.big-box { }
+.left-column { }
+```
+
+### Avoid IDs for Styling
+
+**RECOMMENDED**: Use IDs for JavaScript hooks only, not styling:
+
+```css
+/* ✅ GOOD */
+.header { }
+
+/* ❌ BAD */
+#header { }
+```
+
+**REASON**: IDs have high specificity and are harder to override.
+
+---
+
+## CSS Organization
+
+### Component-Based Organization
+
+**RECOMMENDED**: Organize CSS by component or feature:
+
+```
+styles/
+├── base/
+│   ├── reset.css
+│   ├── typography.css
+│   └── variables.css
+├── components/
+│   ├── button.css
+│   ├── card.css
+│   └── navigation.css
+├── layouts/
+│   ├── grid.css
+│   └── header.css
+└── utilities/
+    └── spacing.css
+```
+
+### Separate Global and Component Styles
+
+```css
+/* global.css - Global styles */
+:root {
+  --color-primary: #007bff;
+  --spacing-unit: 8px;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+/* button.css - Component styles */
+.btn {
+  padding: var(--spacing-unit);
+  background: var(--color-primary);
+}
+```
+
+### CSS Custom Properties (Variables)
+
+**RECOMMENDED**: Use CSS custom properties for theming:
+
+```css
+/* ✅ GOOD: Define at :root */
+:root {
+  --color-primary: #007bff;
+  --color-secondary: #6c757d;
+  --font-family-base: 'Helvetica Neue', sans-serif;
+  --spacing-sm: 8px;
+  --spacing-md: 16px;
+  --spacing-lg: 24px;
+}
+
+.btn {
+  background: var(--color-primary);
+  padding: var(--spacing-md);
+  font-family: var(--font-family-base);
+}
+
+/* Provide fallbacks */
+.btn {
+  background: var(--color-primary, #007bff);
+}
+```
+
+### Avoid @import
+
+**DON'T** use `@import` in CSS (use build tools instead):
+
+```css
+/* ❌ BAD: Blocks rendering */
+@import url('typography.css');
+
+/* ✅ GOOD: Use build tools or multiple <link> tags */
+```
+
+**REASON**: `@import` blocks parallel downloads and slows page load.
+
+---
+
+## CSS Selectors
+
+### Keep Specificity Low
+
+**DO** keep specificity as low as possible:
+
+```css
+/* ✅ GOOD: Low specificity */
+.nav-item { }
+.nav-item.active { }
+
+/* ❌ BAD: High specificity */
+nav ul li a.nav-item { }
+#header .nav ul li a { }
+```
+
+### Limit Nesting
+
+**RECOMMENDED**: Limit nesting to 3 levels maximum:
+
+```css
+/* ✅ GOOD: Shallow nesting */
+.card { }
+.card__header { }
+.card__title { }
+
+/* ❌ BAD: Deep nesting */
+.card .card__header .card__title span.text { }
+```
+
+### Avoid Universal Selector
+
+**USE SPARINGLY**: Universal selector (`*`) can impact performance:
+
+```css
+/* ✅ ACCEPTABLE: Box-sizing reset */
+* {
+  box-sizing: border-box;
+}
+
+/* ❌ BAD: Overly broad */
+* {
+  margin: 0;
+  padding: 0;
+}
+```
+
+### Avoid !important
+
+**AVOID**: Use `!important` only for utilities:
+
+```css
+/* ✅ ACCEPTABLE: Utility class */
+.hidden {
+  display: none !important;
+}
+
+/* ❌ BAD: Regular styling */
+.btn {
+  background: blue !important;
+}
+```
+
+---
+
+## Responsive Design
+
+### Mobile-First Approach
+
+**RECOMMENDED**: Start with mobile styles, add complexity for larger screens:
+
+```css
+/* ✅ GOOD: Mobile-first */
+.container {
+  padding: 16px;
+}
+
+@media (min-width: 768px) {
+  .container {
+    padding: 24px;
+  }
+}
+
+@media (min-width: 1024px) {
+  .container {
+    padding: 32px;
+  }
+}
+
+/* ❌ BAD: Desktop-first */
+.container {
+  padding: 32px;
+}
+
+@media (max-width: 1024px) {
+  .container {
+    padding: 24px;
+  }
+}
+```
+
+### Media Query Units
+
+**RECOMMENDED**: Use `em` or `rem` units for media queries:
+
+```css
+/* ✅ GOOD: em-based (more accessible) */
+@media (min-width: 48em) { /* 768px at 16px base */ }
+@media (min-width: 64em) { /* 1024px at 16px base */ }
+
+/* ❌ ACCEPTABLE: px-based (less flexible) */
+@media (min-width: 768px) { }
+```
+
+### Consistent Breakpoints
+
+**RECOMMENDED**: Define consistent breakpoints:
+
+```css
+:root {
+  --breakpoint-sm: 36em;   /* 576px */
+  --breakpoint-md: 48em;   /* 768px */
+  --breakpoint-lg: 64em;   /* 1024px */
+  --breakpoint-xl: 80em;   /* 1280px */
+}
+
+/* Use in media queries */
+@media (min-width: 48em) { /* md */ }
+@media (min-width: 64em) { /* lg */ }
+```
+
+### CSS Grid and Flexbox
+
+**RECOMMENDED**: Prefer Grid and Flexbox over floats:
+
+```css
+/* ✅ GOOD: Flexbox for 1D layouts */
+.nav {
+  display: flex;
+  gap: 16px;
+  align-items: center;
+}
+
+/* ✅ GOOD: Grid for 2D layouts */
+.gallery {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+  gap: 16px;
+}
+
+/* ❌ BAD: Floats (legacy) */
+.column {
+  float: left;
+  width: 50%;
+}
+```
+
+---
+
+## Code Quality
+
+### Formatting
+
+**RECOMMENDED**: Use consistent formatting:
+
+```css
+/* ✅ GOOD: Consistent formatting */
+.selector {
+  property: value;
+  another-property: value;
+}
+
+.another-selector,
+.multiple-selector {
+  property: value;
+}
+
+/* Use Prettier or Stylelint for automatic formatting */
+```
+
+### Comments
+
+**RECOMMENDED**: Add comments for complex or non-obvious code:
+
+```css
+/* Component: Card
+   Usage: Product listings, blog posts
+   ========================================== */
+.card {
+  /* Prevent content overflow */
+  overflow: hidden;
+}
+
+/* TODO: Refactor to use CSS Grid */
+.legacy-layout {
+  float: left;
+}
+```
+
+### Property Order
+
+**RECOMMENDED**: Group related properties:
+
+```css
+.element {
+  /* Positioning */
+  position: relative;
+  top: 0;
+  left: 0;
+
+  /* Display & Box Model */
+  display: flex;
+  width: 100%;
+  padding: 16px;
+  margin: 0;
+
+  /* Typography */
+  font-size: 16px;
+  line-height: 1.5;
+
+  /* Visual */
+  background: white;
+  border: 1px solid gray;
+
+  /* Misc */
+  cursor: pointer;
+}
+```
+
+---
+
+## Best Practices
+
+### Reset or Normalize
+
+**RECOMMENDED**: Use a CSS reset or normalize:
+
+```css
+/* Option 1: Simple reset */
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+/* Option 2: Use normalize.css or modern-normalize */
+```
+
+### Avoid Inline Styles
+
+**DON'T** use inline styles (use classes instead):
+
+```html
+<!-- ❌ BAD -->
+<div style="color: red; font-size: 16px;">Text</div>
+
+<!-- ✅ GOOD -->
+<div class="error-text">Text</div>
+```
+
+### Use Shorthand Properties
+
+**RECOMMENDED**: Use shorthand when appropriate:
+
+```css
+/* ✅ GOOD: Shorthand */
+.element {
+  margin: 10px 20px;
+  padding: 10px;
+  background: white url('bg.png') no-repeat center;
+}
+
+/* ❌ VERBOSE: Longhand */
+.element {
+  margin-top: 10px;
+  margin-right: 20px;
+  margin-bottom: 10px;
+  margin-left: 20px;
+}
+```
+
+### Vendor Prefixes
+
+**RECOMMENDED**: Use autoprefixer instead of manual prefixes:
+
+```css
+/* ✅ GOOD: Let autoprefixer handle it */
+.element {
+  display: flex;
+  user-select: none;
+}
+
+/* ❌ BAD: Manual prefixes */
+.element {
+  display: -webkit-flex;
+  display: flex;
+  -webkit-user-select: none;
+  user-select: none;
+}
+```
+
+---
+
+## Summary
+
+**Key Principles**:
+1. Use kebab-case for class names
+2. Consider BEM for component naming
+3. Keep specificity low
+4. Limit nesting to 3 levels
+5. Use mobile-first responsive design
+6. Prefer Grid/Flexbox over floats
+7. Use CSS custom properties for theming
+8. Avoid `!important` except for utilities
+9. Use Stylelint for code quality
+
+
+