🔧 docs(architecture): update docs for shared assets

gamaware · gamaware · commit fe456938ff00 · 2026-02-15T00:21:29.000-06:00
📝 Descripción / Description:
- EN: Update docs/README.md and docs/website-architecture.md to reflect the new shared architecture with styles.css, main.js, design tokens, data-theme approach, and additional pages (404.html, learning-resources.html, sitemap.xml, robots.txt)
- ES: Actualizar docs/README.md y docs/website-architecture.md para reflejar la nueva arquitectura compartida con styles.css, main.js, tokens de diseño, enfoque data-theme, y páginas adicionales (404.html, learning-resources.html, sitemap.xml, robots.txt)

📁 Files changed:
- docs/README.md
- docs/website-architecture.md

🏷️ Type: docs
diff --git a/docs/README.md b/docs/README.md
@@ -38,7 +38,12 @@ The website consists of the following main components:
 cloud-devops-labs-index/
 ├── index.html              # Main website page
 ├── access-request.html     # Repository access request form
-├── styles.css              # CSS styles (currently not linked)
+├── learning-resources.html # Learning resources page
+├── 404.html                # Custom 404 error page
+├── styles.css              # Shared design system stylesheet (linked from all pages)
+├── main.js                 # Shared JavaScript module (theme, locale, navigation, animations)
+├── sitemap.xml             # SEO sitemap
+├── robots.txt              # Crawler directives
 ├── docs/                   # Documentation directory
 │   └── README.md           # This documentation file
 ├── .github/
@@ -70,10 +75,10 @@ The website is fully responsive and adapts to different screen sizes:
 
 ### Dark/Light Mode
 
-- Automatic detection of system preference for dark/light mode
-- Manual toggle option in the top-right corner
-- Custom color schemes for both modes with proper contrast
-- OneDark theme for dark mode
+- Automatic detection of system preference via `prefers-color-scheme`
+- Manual toggle with localStorage persistence
+- Theme applied via `data-theme` attribute on `<html>` using CSS custom properties
+- Light and dark palettes defined as design tokens in `styles.css`
 
 ### Multilingual Support
 
@@ -179,10 +184,7 @@ To add support for a new language:
 
 ### Updating Styles
 
-Currently, styles are defined inline in the HTML files. To improve maintainability:
+All styles are defined in the shared `styles.css` file using CSS custom properties (design tokens). To update styles:
 
-1. Move all styles to the `styles.css` file
-2. Link the stylesheet in both HTML files
-3. Remove inline styles from HTML
-
-This will make future styling updates more efficient and consistent.
+1. Edit the design tokens in `:root` (light theme) or `[data-theme="dark"]` (dark theme) in `styles.css`
+2. Changes automatically apply to all pages that link the shared stylesheet
diff --git a/docs/website-architecture.md b/docs/website-architecture.md
@@ -37,43 +37,24 @@ graph TD
 
 ### Responsive Design Implementation
 
-The responsive design is implemented using:
+The responsive design is implemented using a mobile-first approach:
 
 1. **Fluid Layouts**: Using relative units and percentages
 2. **CSS Grid and Flexbox**: For flexible content arrangement
-3. **Media Queries**: Targeting different screen sizes
-   - `@media (max-width: 768px)`: Tablet and smaller devices
+3. **Design Tokens**: CSS custom properties in `styles.css` for consistent spacing, typography, and colors
+4. **Media Queries**: Targeting different screen sizes
    - `@media (max-width: 480px)`: Mobile devices
+   - `@media (max-width: 768px)`: Tablet and smaller devices
+   - `@media (max-width: 1024px)`: Small desktop
 
 ### Theme Switching Logic
 
-The theme switching functionality works as follows:
-
-1. **Initial Theme Detection**:
-   ```javascript
-   const prefersDarkScheme = window.matchMedia('(prefers-color-scheme: dark)');
-   
-   if (localStorage.getItem('theme') === 'dark' || 
-       (!localStorage.getItem('theme') && prefersDarkScheme.matches)) {
-       document.body.classList.add('dark-mode');
-       themeIcon.classList.replace('fa-moon', 'fa-sun');
-   }
-   ```
-
-2. **Theme Toggle Handler**:
-   ```javascript
-   themeToggle.addEventListener('click', () => {
-       document.body.classList.toggle('dark-mode');
-       
-       if (document.body.classList.contains('dark-mode')) {
-           localStorage.setItem('theme', 'dark');
-           themeIcon.classList.replace('fa-moon', 'fa-sun');
-       } else {
-           localStorage.setItem('theme', 'light');
-           themeIcon.classList.replace('fa-sun', 'fa-moon');
-       }
-   });
-   ```
+The theme is applied via a `data-theme` attribute on the `<html>` element, which swaps CSS custom property values defined in `styles.css`. The `ThemeEngine` module in `main.js` handles detection, toggling, and persistence:
+
+1. **Initial Theme Detection**: Checks localStorage first, then falls back to `prefers-color-scheme` media query
+2. **Theme Application**: Sets `data-theme="dark"` or `data-theme="light"` on `<html>`, which activates the corresponding CSS custom property set
+3. **Toggle & Persistence**: Manual toggle saves preference to localStorage; OS changes are tracked via `matchMedia` change listener
+4. **No Flash**: Theme is applied before body renders since `data-theme` is set on `<html>`
 
 ### Language Switching Implementation
 
@@ -191,9 +172,8 @@ The GitHub Actions workflow includes security measures:
 
 ### Future Optimization Opportunities
 
-1. **CSS Optimization**: Move styles to external stylesheet
-2. **Image Optimization**: Further compress and optimize images
-3. **Caching Strategies**: Implement better caching for static resources
+1. **Image Optimization**: Further compress and optimize images
+2. **Caching Strategies**: Implement better caching for static resources
 
 ## Testing Procedures
 
