css-variables-mapping.md

CSS Variables Standardization Project

This document tracks all CSS variable standardization work completed in the "magic-worlds" project. We've replaced all non-standard CSS variables with standardized ones from /src/ui/styles/variables/.

Files Updated

The following files have been updated to use standard variables:

1. /home/andres/WebstormProjects/magic-worlds/src/ui/components/ConfirmDialog.css
2. /home/andres/WebstormProjects/magic-worlds/src/ui/components/Header.css
3. /home/andres/WebstormProjects/magic-worlds/src/ui/components/LoadingSpinner.css
4. /home/andres/WebstormProjects/magic-worlds/src/ui/components/common/EmptyState.css
5. /home/andres/WebstormProjects/magic-worlds/src/ui/components/lists/lists.css
6. /home/andres/WebstormProjects/magic-worlds/src/ui/components/lists/Card/Card.css
7. /home/andres/WebstormProjects/magic-worlds/src/features/characters/components/CharacterCreator.css
8. /home/andres/WebstormProjects/magic-worlds/src/features/worlds/components/WorldCreator.css
9. /home/andres/WebstormProjects/magic-worlds/src/features/interaction/components/InteractionCenterPanel.css
10. /home/andres/WebstormProjects/magic-worlds/src/features/interaction/components/InteractionLeftPanel.css
11. /home/andres/WebstormProjects/magic-worlds/src/features/interaction/components/InteractionRightPanel.css
12. /home/andres/WebstormProjects/magic-worlds/src/features/interaction/components/AdventureInteraction.css
13. /home/andres/WebstormProjects/magic-worlds/src/features/landing/components/LandingPage.css
14. /home/andres/WebstormProjects/magic-worlds/src/features/adventures/components/AdventureCreator.css
15. /home/andres/WebstormProjects/magic-worlds/src/ui/styles/App.css
16. /home/andres/WebstormProjects/magic-worlds/src/ui/styles/base/forms.css
17. /home/andres/WebstormProjects/magic-worlds/src/ui/styles/base/buttons.css
18. /home/andres/WebstormProjects/magic-worlds/src/ui/styles/base/reset.css
19. /home/andres/WebstormProjects/magic-worlds/src/ui/styles/base/layout.css
20. /home/andres/WebstormProjects/magic-worlds/src/ui/styles/index.css

Variable Mappings Applied

Non-standard Variable	Standard Variable Used
--color-surface	--background-color-primary
--color-background	--background-color-secondary
--color-background-secondary	--background-color-tertiary
--color-text	--text-color
--color-text-primary	--text-color
--color-text-secondary	--text-color-secondary
--color-primary	--accent-color
--color-primary-dark	--accent-color-hover
--color-border	--border-color
--border-radius	--border-radius-small
--spacing-sm	--padding-small or --gap-small (context dependent)
--spacing-md	--padding-medium or --gap-medium (context dependent)
--spacing-lg	--padding-large or --gap-large (context dependent)
--spacing-xl	--gap-xs
--spacing-xs	--padding-small
--font-size-sm	--font-size-small
--font-size-lg	--font-size-large
--font-size-xl	--font-size-large
--font-size-xs	Direct value: 0.75rem
--font-size-base	Direct value: 1rem
--line-height-base	--line-height-normal
--line-height-tight	--line-height-normal
--font-weight-semibold	Direct value: 600
--font-weight-bold	Direct value: 700
--font-weight-medium	Direct value: 500
--font-weight-normal	Direct value: 400
--shadow-md	--box-shadow-medium
--border-standard	1px solid var(--border-color)
--border-focus	Direct value with --accent-color
--color-primary-rgb	--background-transparency-light
--color-error-rgb	--color-error-transparency
--color-success-rgb	--color-success-transparency
--color-error-dark	--color-error-hover
--color-success-dark	--color-success-hover
--color-messages-error	--color-error
--spin 1s linear infinite	--spin-animation
transition with ease values	--transition-standard

Implementation Notes

1. All variable replacements were done with existing variables from /src/ui/styles/variables/, without creating any new ones.
2. For font weights, we used direct values (400, 500, 600, 700) where no variables existed.
3. For all spacing variables, we mapped to the appropriate standard variable based on context (padding vs margin vs gap).
4. All custom animation values were replaced with the --spin-animation and --transition-standard variables.
5. Color RGB values were replaced with appropriate transparency variables.
6. Maintained consistent spacing throughout components using the standard spacing variables.
7. Kept system variables like --color-error and --color-success as they appear to be part of the standard set.

Consistency Benefits

1. Improved maintainability: Any future theme changes can now be made in one central location.
2. Better visual consistency: Using standardized variables ensures a more cohesive appearance across the entire application.
3. Reduced CSS size: Eliminated duplicate custom variables that were serving the same purpose.
4. Simplified developer experience: Developers now only need to learn one set of variable names.
5. Better dark/light theme support: All components now use the same variable structure for theming.
6. Easier onboarding: New team members will have a consistent variable system to learn.

Verification Process

These commands were used to verify that all non-standard variables were replaced:

grep -r "\--color-" --include="*.css" /home/andres/WebstormProjects/magic-worlds | grep -v "node_modules" | grep -v "variables" | grep -v "dist" | grep -v "build"

grep -r "\--spacing-" --include="*.css" /home/andres/WebstormProjects/magic-worlds | grep -v "node_modules" | grep -v "variables" | grep -v "dist" | grep -v "build"

find /home/andres/WebstormProjects/magic-worlds -name "*.css" | grep -v "node_modules" | grep -v "src/ui/styles/variables" | xargs grep -l "\--" | sort

Future Recommendations

1. Style Linting: Consider adding a CSS/SCSS linter with rules to enforce usage of standard variables.
2. Documentation: Keep this mapping document updated if new standard variables are added.
3. Component Library: Consider developing a component library that uses these standardized variables.
4. Theming: Leverage the standardized variables for implementing dark/light mode or custom themes.