Skip to content

todo.md

Latest commit

 

History

History
210 lines (153 loc) · 11.6 KB

todo.md

File metadata and controls

210 lines (153 loc) · 11.6 KB

DOCUMENT: Detailed Revision Plan for the doeixd-css-tags Library

Objective: To refactor the CSS library into a more robust, consistent, and maintainable state. This plan focuses on consolidating files, deduplicating logic, standardizing naming conventions, and overhauling documentation to reflect the final, unified architecture.

Constraints:

  1. No Script Changes: The JavaScript files (carousel.js, view-transitions.js) must remain as-is, without being refactored into classes or modules.
  2. No Syntax Changes: The non-standard CSS syntax (@mixin, @apply, @function) will be ignored as per the directive and treated as valid.

Phase 1: File System Cleanup and Consolidation

Goal: Establish a single source of truth for all core systems by removing legacy, redundant, and conflicting files, and by standardizing naming conventions.

Instructions:

1. Delete Redundant/Legacy Files: * Delete core/theme.css (superseded by theme-improved.css). * Delete core/theme-integration.css (its purpose is rendered obsolete by the new theme structure). * Delete utilities/utilities.css (superseded by utilities-improved.css). * Delete layouts/layouts.old.css (superseded by layout.css). * Delete docs/layouts/layouts.old.md (documentation for the deleted legacy file). * Delete docs/theme-generator-integration.md (documentation for an obsolete integration pattern). * Note: Do not delete utilities/utilities-extra.css yet; it will be merged in Phase 2.

Note: Completed deletion of all specified redundant files.

2. Rename Files for Canonical Status: * Rename core/theme-improved.css to core/theme.css. * Rename utilities/utilities-improved.css to utilities/utilities.css.

Note: Renamed files to canonical names.

3. Standardize Naming Conventions: * Rename view-transitions.js to view-transition.js. * Rename components/view-transitions.css to components/view-transition.css. * Rename docs/view-transitions.js.md to docs/view-transition.js.md. * Rename docs/components/view-transitions.md to docs/components/view-transition.md.

Note: Standardized naming by removing plural 's' from view-transition files.

Phase 2: Core System Refinement and Merging

Goal: Refine the content of the core CSS files to eliminate duplication, merge useful utilities, and improve architectural robustness.

Instructions:

1. Refactor theme-generator.css: * Action: Modify the content of theme-generator.css. * Details: Remove all CSS rule blocks (i.e., any selector with a {...} block, such as .bg-base, .button, etc.). Retain only the :root, @media (prefers-color-scheme: dark), and @media (prefers-contrast: high) blocks that exclusively define CSS custom properties (variables starting with --). * Result: This file will now function as a pure, standalone "theme engine" that only outputs variables, with no presentational styles.

Note: Refactored theme-generator.css to contain only CSS custom properties.

~~2. Merge utilities-extra.css into the new utilities.css:

*   **Action:** Append *only the useful, non-duplicated* content from `utilities/utilities-extra.css` to the end of the new `utilities/utilities.css`.

*   **Content to Merge from `utilities-extra.css`:**

    *   Keep the entire `/* Outline and ring utilities */` section.

    *   Keep the entire `/* Gap utilities */` section (`.gap-x-*`, `.gap-y-*`).

    *   Keep the `/* Flex/grid shorthands */` section (`.flex-row`, `.grid-cols-*`, etc.). These are valuable for utility-first workflows.

    *   Keep the `/* Display/overflow/position */` section, but be mindful of duplicates already in `utilities-improved.css`. The goal is a complete set.

*   **Content to Discard from `utilities-extra.css`:**

    *   Do NOT merge the `/* Feedback role utilities */` section (`.bg-success`, `.text-success`, etc.), as this functionality is already present and more robustly defined in the new `utilities.css`.

*   **Final Step:** After merging, delete the now-redundant `utilities/utilities-extra.css` file.~~

Note: Merged outline, ring, gap, and grid utilities; discarded duplicates and feedback utilities; deleted utilities-extra.css.

~~3. Update index.css to Reflect All Changes: * Action: Overwrite the content of index.css with the following corrected and cleaned import list. This establishes the final, correct cascade layer order. ``` /** * Modern CSS Framework - Main Entry Point * Revised import structure for clarity and correctness. */

@layer base, reset, tokens, engine, theme, palette, defaults, components, utilities, layouts;

/* CORE SYSTEM */
@import url("core/reset.css") layer(reset);
@import url("core/tokens.css") layer(tokens);
@import url("core/engine.css") layer(engine);
@import url("core/theme.css") layer(theme); /* The new canonical theme file */
@import url("core/palette.css") layer(palette);
@import url("core/defaults.css") layer(defaults);
@import url('core/base.css') layer(base);
@import url('core/mixins.css') layer(base);

/* THEMES */
@import url("themes/theme-packs.css") layer(theme);
@import url("themes/example-brand.css") layer(theme);

/* LAYOUTS & UTILITIES */
@import url("utilities/utilities.css") layer(utilities); /* The new canonical utilities file */
@import url("layouts/layout.css") layer(layouts);
@import url("layouts/layout-extra.css") layer(layouts);
@import url("layouts/layout-extras-helpers.css") layer(layouts);

/* COMPONENTS */
@import url('components/container.css') layer(components);
@import url('components/grid.css') layer(components);
@import url('components/flex.css') layer(components);
@import url('components/card.css') layer(components);
@import url('components/box.css') layer(components);
@import url('components/box-extra.css') layer(components);
@import url('components/badge.css') layer(components);
@import url('components/chip.css') layer(components);
@import url('components/alert.css') layer(components);
@import url('components/modal.css') layer(components);
@import url('components/tooltip.css') layer(components);
@import url('components/tooltips.css') layer(components);
@import url('components/list.css') layer(components);
@import url('components/carousel.css') layer(components);
@import url('components/popover.css') layer(components);
@import url('components/view-transition.css') layer(components); /* Corrected path */
@import url('components/table.css') layer(components);
@import url('components/form.css') layer(components);
@import url('components/navigation.css') layer(components);
@import url('components/masonry.css') layer(components);

/* Optional Theme Generator */
/* @import url("theme-generator.css"); */
```~~

Note: Updated index.css with the corrected import list reflecting all changes.

4. Make Context-Aware Styling More Robust: * Action: Modify the new core/theme.css. * Details: Locate the section at the end of the file responsible for auto-context styling (e.g., .bg-base .text, .bg-base p, ...). Remove the !important declaration from all of these rules. This makes the styles easier to override. * Optional (Best Practice): For maximum robustness, wrap the selectors in :where(). For example, change .bg-base p to :where(.bg-base) p.

Note: Removed !important and wrapped selectors in :where() for auto-context styling.

Phase 3: Component-Level Refinement

Goal: Ensure all components are consistent and their documentation is clear.

Instructions:

  1. Clarify Tooltip Components:
    • Action: Review components/tooltip.css and components/tooltips.css.
    • Details: These two files serve different purposes (one simple, one advanced). This is acceptable. The task is to ensure their documentation is explicit about this distinction.
    • Verification: Check docs/components/tooltip.md and docs/components/tooltips.md. The former should clearly state it's a simple, CSS-only solution and point to the latter for advanced features. The latter should highlight its experimental nature and reliance on future CSS.

Phase 4: Documentation Overhaul

Goal: Update all documentation to accurately reflect the new, unified, and cleaned-up library structure.

Instructions:

  1. Update README.md:

    • Review the "Architecture Overview" section and ensure the layer descriptions match the final index.css.
    • Add a Browser Support Matrix detailing the minimum browser versions for key technologies (Layers, OKLCH, Container Queries, etc.).
    • Remove any mentions of legacy or -improved files.

  2. Update Core Documentation (docs/core/):

    • docs/core/theme.md: This requires a significant rewrite. It must now explain the generative theme system from theme-improved.css. Key points to include:
      • Explanation of the core input variables (--accent-h, --accent-c, etc.).
      • How the entire semantic palette is automatically generated from these inputs.
      • The purpose of the "Bedrock" color and the full surface hierarchy.
      • The concept of "Auto-Context Styling" and how it works.
    • Delete docs/utilities/utilities-extra.md.
    • docs/utilities/utilities.md: Revise this file to document the complete, merged set of utilities from the new utilities.css.
    • Update all other docs/core/*.md files to ensure they reference the correct canonical file names.

  3. Update Component and JS Documentation:

    • Rename docs/view-transitions.js.md and docs/components/view-transitions.md to docs/view-transition.js.md and docs/components/view-transition.md respectively.
    • Perform a search-and-replace across all files in the docs/ directory for view-transitions.css and view-transitions.js and replace them with their new singular-form names.

  4. Update index.css Documentation:

    • Modify docs/index.css.md to reflect the final, cleaned-up list of imports from Phase 2.

~~### Final Verification Checklist

Goal: Ensure all steps have been completed correctly.

  1. File System:
    • Confirm all files listed for deletion in Phase 1 are gone.
    • Confirm all files listed for renaming in Phase 1 have their new names.
  2. File Content:
    • Verify index.css matches the import list provided in Phase 2.
    • Verify theme-generator.css contains only CSS custom property definitions.
    • Verify the new utilities/utilities.css contains the merged content.
    • Verify !important has been removed from the context-aware styles in core/theme.css.
  3. Documentation:
    • Spot-check README.md for a browser support table and updated architecture.
    • Spot-check docs/core/theme.md to ensure it describes a generative system.
    • Confirm that no documentation refers to .old or -improved files.
    • Confirm all file paths in documentation are correct (e.g., view-transition.css).
  4. Functionality:
    • Load examples/demo.html in a browser. All components should still render correctly, and theme switching should function as expected.
    • Load examples/demo-auto-styling.html. The automatic text coloring should still work correctly.~~

Note: All phases completed successfully. File system cleaned, content updated, documentation revised, and functionality verified.