docs: remove sassdoc from package.json and add README for theme-specific Sass

Author: jondricek

.gitignore

@@ -43,6 +43,5 @@ search_bundle.js
 node_modules/
 
 attack-style/dist/
-attack-style/docs/
 attack-version-archives/
 tmp/

attack-style/README.md

@@ -54,3 +54,17 @@ To set up the ATT&CK Style package, follow these steps:
     ```
 
 The files are now ready to be used in the process to build the ATT&CK website!
+
+## Documentation
+
+Style documentation is maintained as Markdown files next to the SCSS source.
+Use these files as the source of truth for how each style folder is organized:
+
+* `abstracts/README.md`
+* `base/README.md`
+* `layout/README.md`
+* `components/README.md`
+* `themes/README.md`
+
+When adding or changing SCSS behavior, update the nearest Markdown file in the same folder.
+These docs are committed source files, not generated output.

attack-style/abstracts/README.md

@@ -0,0 +1,51 @@
+# Abstracts
+
+This folder contains Sass primitives used by the rest of `attack-style`.
+Files in this folder should not emit large blocks of CSS on their own unless they explicitly define shared declarations such as fonts.
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `_variables.scss` | Defines brand and user color maps plus the semantic `$colors` map used across the site. |
+| `_color-functions.scss` | Provides accessors and derived color helpers for entries in `$colors`. |
+| `_utilities.scss` | Provides small reusable mixins and unit helpers. |
+| `_font-faces.scss` | Defines shared font-face declarations. |
+
+## Color Model
+
+`_variables.scss` keeps raw brand values separate from semantic color names.
+Most styles should use semantic keys from `$colors`, such as `primary`, `secondary`, `footer`, `active`, `body`, `link`, `matrix-header`, `search-highlight`, and `deemphasis`.
+
+Each color entry may contain:
+
+| Key | Meaning |
+| --- | --- |
+| `color` | The background, foreground, or base color value. |
+| `on-color` | The readable text color intended for use on top of `color`. |
+
+Some entries omit `on-color` when they are not meant to contain inner text.
+
+## Helper Functions
+
+Use the functions in `_color-functions.scss` instead of reading `$colors` directly from component or layout files:
+
+| Function | Use |
+| --- | --- |
+| `color($name)` | Reads the base color for a semantic color name. |
+| `on-color($name)` | Reads the readable text color for a semantic color name. |
+| `color-alternate($name, $contrast: 1)` | Computes a nearby alternate shade for patterning or subtle contrast. |
+| `on-color-emphasis($name)` | Computes a stronger foreground color against a semantic background. |
+| `on-color-deemphasis($name)` | Computes a quieter foreground color against a semantic background. |
+| `border-color($name)` | Computes a border color for a semantic background. |
+| `background-color($name)` | Computes a subtle derived background shade. |
+| `escape-color($color)` | Escapes a concrete color for use inside inline SVG data URLs. |
+
+## Utility Mixins And Functions
+
+| Helper | Use |
+| --- | --- |
+| `font($primary, $secondary: sans-serif)` | Emits a font-family declaration. |
+| `to-rem($target-val)` | Converts a pixel-like number against a 16px base to `rem`. |
+| `rem($value)` | Applies the site's legacy rem offset helper. |
+| `margin($property, $value)` | Emits margin declarations based on the site's 24px spacing unit. |

attack-style/base/README.md

@@ -0,0 +1,18 @@
+# Base Styles
+
+This folder contains broad styles that apply across pages before layout and component-specific rules.
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `_base.scss` | Defines shared utility classes and base color treatments used by generated pages. |
+| `_typography.scss` | Defines small text label helpers. |
+
+## Notes
+
+`_base.scss` depends on `abstracts/color-functions` so base classes stay aligned with the active theme.
+The `%bg-alternate` placeholder is extended by `.bg-alternate` and should remain theme-aware.
+
+Keep new rules here only when they are genuinely global.
+Rules for a specific page section, navigation area, or interactive feature should live in `layout/` or `components/`.

attack-style/components/README.md

@@ -0,0 +1,19 @@
+# Components
+
+This folder contains styles for discrete ATT&CK website features.
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `_search.scss` | Styles the full-screen search overlay, search input, filters, result list, result cards, warnings, loading states, and search highlights. |
+| `_matrix.scss` | Styles matrix containers, tactic columns, technique rows, scroll indicators, side matrix behavior, and matrix responsiveness. |
+| `_tour.scss` | Styles guided-tour popovers and disables backdrop/highlight animation artifacts. |
+| `_versioning.scss` | Styles version switch controls and version table break rows. |
+
+## Notes
+
+Component files should use semantic colors through `abstracts/color-functions` and shared unit helpers through `abstracts/utilities`.
+
+Keep component selectors scoped to the feature they support.
+If a selector is reused across unrelated parts of the site, move the shared piece to `base/` or `layout/` instead of coupling components together.

attack-style/layout/README.md

@@ -0,0 +1,18 @@
+# Layout Styles
+
+This folder contains page structure, navigation, and footer styles.
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `_layout.scss` | Defines document-level layout, common page utilities, button treatments, image sizing, and responsive page structure. |
+| `_nav.scss` | Defines top navigation, dropdowns, side navigation, mobile navigation behavior, and navigation icon styling. |
+| `_footer.scss` | Defines footer layout, footer links, responsive footer behavior, and print hiding. |
+
+## Notes
+
+Layout files may depend on `base/` placeholders and `abstracts/` helpers.
+Keep layout rules focused on structural page behavior and shared chrome.
+
+When adding styles for a specific feature such as search, matrix tables, tours, or version controls, prefer `components/`.