kempo-css 1.0.7 → 1.0.9

package/.github/copilot-instructions.md

@@ -0,0 +1,165 @@
+# Code Contribution Guidelines
+
+## Project Structure
+
+ - All code should be in the `src/` directory, with the exception of npm scripts.
+ - All components should be in the `src/components/` directory.
+ - All utility function module files should be in the `src/utils/` directory.
+ - All documnentation should be in the `docs/` directory. This directory is used by GitHub as the "GitHub Pages", so all links need to be relative, and there will be a build script which copies all code to the `docs/` directory.
+
+## Coding Style Guidelines
+
+### Code Organization
+Use multi-line comments to separate code into logical sections. Group related functionality together.
+  - Example: In Lit components, group lifecycle callbacks, event handlers, public methods, utility functions, and rendering logic separately.
+
+```javascript
+/*
+  Lifecycle Callbacks
+*/
+```
+
+### Avoid single-use variables/functions
+Avoid defining a variable or function to only use it once; inline the logic where needed. Some exceptions include:
+  - recursion
+  - scope encapsulation (IIFE)
+  - context changes
+
+### Minimal Comments, Empty Lines, and Spacing
+
+Use minimal comments. Assume readers understand the language. Some exceptions include:
+  - complex logic
+  - anti-patterns
+  - code organization
+
+Do not put random empty lines within code; put them where they make sense for readability, for example:
+  - above and below definitions for functions and classes.
+  - to help break up large sections of logic to be more readable. If there are 100 lines of code with no breaks, it gets hard to read.
+  - above multi-line comments to indicate the comment belongs to the code below
+
+No  empty lines in css.
+
+End each file with an empty line.
+
+End each line with a `;` when possible, even if it is optional.
+
+Avoid unnecessary spacing, for example:
+  - after the word `if`
+  - within parentheses for conditional statements
+
+```javascript
+let count = 1;
+
+const incrementOdd = (n) => {
+  if(n % 2 !== 0){
+    return n++;
+  }
+  return n;
+};
+
+count = incrementOdd(count);
+```
+
+### Prefer Arrow Functions
+Prefer the use of arrow functions when possible, especially for class methods to avoid binding. Use normal functions if needed for preserving the proper context.
+ - For very basic logic, use implicit returns
+ - If there is a single parameter, omit the parentheses.
+```javascript
+const addOne = n => n + 1;
+```
+
+### Module Exports
+  - If a module has only one export, use the "default" export, not a named export.
+    - Do not declare the default export as a const or give it a name; just export the value.
+
+```javascript
+export default (n) => n + 1;
+```
+  - If a module has multiple exports, use named exports and do not use a "default" export.
+
+### Code Reuse
+Create utility functions for shared logic.
+  - If the shared logic is used in a single file, define a utility function in that file.
+  - If the shared logic is used in multiple files, create a utility function module file in `src/utils/`.
+
+### Naming
+Do not prefix identifiers with underscores.
+  - Never use leading underscores (`_`) for variable, property, method, or function names.
+  - Use clear, descriptive names without prefixes.
+  - When true privacy is needed inside classes, prefer native JavaScript private fields (e.g., `#myField`) instead of simulated privacy via underscores.
+
+## Components
+
+### Base Component Architecture
+
+The project provides three base components for different rendering strategies. Choose the appropriate base component and extend it:
+
+#### ShadowComponent
+For components that need shadow DOM encapsulation and automatic `/kempo.css` stylesheet injection.
+
+```javascript
+import ShadowComponent from './ShadowComponent.js';
+
+export default class MyComponent extends ShadowComponent {
+  render() {
+    return html`<p>Shadow DOM content with scoped styles</p>`;
+  }
+}
+```
+
+#### LightComponent  
+For components that render directly to light DOM without shadow DOM encapsulation.
+
+```javascript
+import LightComponent from './LightComponent.js';
+
+export default class MyComponent extends LightComponent {
+  renderLightDom() {
+    return html`<p>Light DOM content</p>`;
+  }
+}
+```
+
+#### HybridComponent
+For components that need both shadow DOM (with automatic `/kempo.css`) and light DOM rendering.
+
+```javascript
+import HybridComponent from './HybridComponent.js';
+
+export default class MyComponent extends HybridComponent {
+  render() {
+    return html`<p>Shadow DOM content</p>`;
+  }
+  
+  renderLightDom() {
+    return html`<p>Light DOM content alongside natural children</p>`;
+  }
+}
+```
+
+**Important:** Always call `super.updated()` when overriding the `updated()` method in LightComponent or HybridComponent to ensure proper rendering.
+
+### Component Architecture and Communication
+
+- Use methods to cause actions; do not emit events to trigger logic. Events are for notifying that something already happened.
+  - Prefer `el.closest('ktf-test-framework')?.enqueueSuite({...})` over firing an `enqueue` event.
+
+- Wrap dependent components inside a parent `ktf-test-framework` element. Children find it via `closest('ktf-test-framework')` and call its methods. The framework can query its subtree to orchestrate children.
+
+- Avoid `window` globals and global custom events for coordination. If broadcast is needed, scope events to the framework element; reserve window events for global, non-visual concerns (e.g., settings changes).
+
+## Development Workflow
+
+### Local Development Server
+- **DO NOT** start a development server - one is already running
+- Default port: **8083**
+- Base URL: `http://localhost:8083`
+- Documentation URLs follow the directory/file structure in `docs/` (e.g., `docs/components/color-picker.html` → `http://localhost:8083/components/color-picker.html`)
+- Use this server for all testing and verification
+
+### Testing and Verification
+- **ALWAYS** verify changes using the live documentation on the running server
+- Use Chrome DevTools Protocol (chrome-devtools-mcp) for interactive testing
+- **DO NOT** create one-off test files or framework-less tests
+- Test components in their natural documentation environment
+- Validate both functionality and visual appearance

package/.github/prompts/build-theme-editor.prompt.md

@@ -0,0 +1,89 @@
+---
+mode: "agent"
+tools: ['edit', 'runNotebooks', 'search', 'new', 'runCommands', 'runTasks', 'chromedevtools/chrome-devtools-mcp/*', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'openSimpleBrowser', 'fetch', 'githubRepo', 'extensions', 'todos', 'runSubagent']
+---
+
+# Theme Editor
+
+## Background
+kempo-css can be customized by the consumer by creating their own theme file (css) which overwrites the CSS Custom Properties defined in `src/kempo.css`, the file should not overwrite the actual style properties of elements, only overwrite CSS Custom Properties.
+
+## Description
+
+### Page Layout
+The theme editor" is a GUI which allows consumers to create and download a theme file. The page should be spit into 3 sections:
+  1. Navigation: The navbar is on top of the page.
+  2. Theme Editor: A set of inputs on the left side of the page, this should be full height (except the navigation) and be independently scrollable.
+     - This should have two sections, the top is a download / upload buttons, and a theme select.
+  3. Demo: HTML Elements that serve as examples to the user so they can see how their changes will affect the page. This should also be independently scrollable.
+
+### Changing the theme
+There should be two ways to change the theme.
+  - A `k-theme-switcher` component in the navigation bar (supports auto/light/dark) - already in place.
+  - A select dropdown on the top of the theme editor which allows the user to choose between "dark" and "light" (no "auto" option). This controls which theme's colors are being edited in the color pickers below. 
+  - The select dropdown should subscribe to the theme context to stay in sync when the theme changes via the `k-theme-switcher`. When "auto" is detected, resolve it to the actual current theme (light or dark) using the theme util.
+ 
+## Resources
+
+### Kempo-UI
+The theme editor should be built using the kempo-ui component library, which is based on Lit. Kempo-UI has already been installed as an external library.
+  - If new components need to be created for this feature, they should be placed in `src/components/` following the project's base component architecture (ShadowComponent, LightComponent, or HybridComponent).
+  - The "theme" utility should be used to get / set the theme and subscribe to theme changes.
+    - https://dustinpoissant.github.io/kempo-ui/utils/theme.html
+  - The "context" utility should be used to store the theme overwrites and synchronize UI state.
+    - https://dustinpoissant.github.io/kempo-ui/utils/context.html
+  - The "Color Picker" component should be used in the GUI.
+    - https://dustinpoissant.github.io/kempo-ui/components/color-picker.html
+  - The "Dialog" component should be used to allow the user to upload an existing theme for editing.
+    - https://dustinpoissant.github.io/kempo-ui/components/dialog.html
+ 
+### chrome-devtools-mcp
+The page is already running at http://localhost:4048/theme-editor.html there is no need to start a server, just use the chrome-devtools-mcp to verify that the theme editor is working exactly as expected.
+
+## Phases
+
+  0. Create a custom component `k-theme-property-input` in `src/components/` that handles CSS custom property values.
+     - This component should detect if the value is a CSS custom property reference (contains `var(--`).
+     - It should provide a toggle/switch to choose between "Custom Value" and "Reference Property".
+     - When in "Custom Value" mode for colors, show a `k-color-picker`.
+     - When in "Reference Property" mode, show a select dropdown listing all available CSS custom properties (filtered to relevant types, e.g., only color properties for color values).
+     - For properties with `light-dark()`, handle both the light and dark values, which may each independently be either a color or a property reference.
+     - The component should emit a change event with the full value (e.g., `var(--c_primary)` or `rgb(51, 102, 255)`).
+     - Use the chrome-devtools-mcp to verify this component works correctly in isolation before moving on.
+  1. Create a JavaScript object that is the default theme.
+     - This can be determined by looking at `src/kempo.css` and seeing what CSS Custom Properties are defined in the `:root` rule.
+     - The object structure should store light and dark values separately for properties using `light-dark()`, and preserve `var()` references:
+  2. Create the inputs for the CSS Custom Properties, the default values should be the default values from phase 1.
+     - For color CSS Custom Properties that use `light-dark()`, show one `k-theme-property-input` per property. The displayed value should reflect the current editing theme (selected in the theme editor dropdown, not necessarily the applied theme).
+     - The `k-theme-property-input` component should handle both direct color values and `var()` references automatically.
+     - Group inputs logically: Colors first (primary, secondary, danger, warning, success, backgrounds, text colors), then typography (fonts, sizes, weights), then spacing/layout, then other properties.
+     - For each input, add a label showing the CSS variable name (e.g., "Primary Color (--c_primary)").
+     - The demo content is already loaded via `<k-import src="./docs.inc.html">` in the right pane and includes examples of all themed elements.
+     - Use the chrome-devtools-mcp to verify the page looks correct before moving on to the next phase.s-is
+         // ... etc
+       }
+       ```
+     - Log it to the devtools console and verify using the chrome-devtools-mcp before moving on to the next phase.
+  2. Create the inputs for the CSS Custom Properties, the default values should be the default values from phase 1.
+     - For color CSS Custom Properties that use `light-dark()`, show one `k-color-picker` per property. The displayed value should reflect the current editing theme (selected in the theme editor dropdown, not necessarily the applied theme).
+     - Group inputs logically: Colors first (primary, secondary, danger, warning, success, backgrounds, text colors), then typography (fonts, sizes, weights), then spacing/layout, then other properties.
+     - For each color picker, add a label showing the CSS variable name (e.g., "Primary Color (--c_primary)").
+     - The demo content is already loaded via `<k-import src="./docs.inc.html">` in the right pane and includes examples of all themed elements.
+     - Use the chrome-devtools-mcp to verify the page looks correct before moving on to the next phase. 
+  3. Create an event listener that listens for any change on any input, creates a new "theme" object, compares that to the default theme object from phase 1 to create a "diff" object.
+  4. Create a theme css string from the diff object.
+     - Convert the diff object back into CSS custom properties with `light-dark()` functions where appropriate.
+     - The CSS should be wrapped in a `:root` selector.
+     - Apply this theme by injecting it into a `<style id="custom-theme">` tag in the head, replacing any existing custom theme.
+     - Save the CSS string to kempo-ui context for later download.
+     - Log the CSS string to the devtools console.
+     - Use the chrome-devtools-mcp to verify that the page looks correct and the CSS string in the devtools console looks correct:
+       - Change a color input for the light theme, verify the page updates immediately when in light mode.
+       - Switch to dark theme in the editor dropdown, change a dark color, verify the page updates when in dark mode.
+       - Change a non-color input (e.g., font size, spacing) and verify the page updates across both themes.sole looks correct.
+       - Change a color input and verify that the page is updating and looks by looking at the demo.
+       - Change a non-color input and verify that the page is updating and looks correct by looking at the demo. 
+  5. Hookup the "Download" button so that when the user clicks it, it downloads the minimal (diff) theme.
+      - If you have a way to verify this automatically attempt it but I might have to verify this manually, im not sure if AI agents can save the file and verify it. Ask me to save the file, i will then attach the theme file to the chat context so you can verify it looks correct.
+  6. Hookup the "Upload" button, it should use the kempo-ui Dialog to open a dialog that allows the user to upload a theme file, then when they click "Apply" it will will update the inputs on the page.
+      - If you have a way to verify this automatically attempt it, but I might have to verify this manually.

package/LICENSE.md

@@ -0,0 +1,91 @@
+# Creative Commons Attribution-NonCommercial-ShareAlike 2.0
+
+CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM ITS USE.
+
+## License
+
+THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.
+
+BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS.
+
+### 1. Definitions
+
+a. "Collective Work" means a work, such as a periodical issue, anthology or encyclopedia, in which the Work in its entirety in unmodified form, along with a number of other contributions, constituting separate and independent works in themselves, are assembled into a collective whole. A work that constitutes a Collective Work will not be considered a Derivative Work (as defined below) for the purposes of this License.
+
+b. "Derivative Work" means a work based upon the Work or upon the Work and other pre-existing works, such as a translation, musical arrangement, dramatization, fictionalization, motion picture version, sound recording, art reproduction, abridgment, condensation, or any other form in which the Work may be recast, transformed, or adapted, except that a work that constitutes a Collective Work will not be considered a Derivative Work for the purpose of this License. For the avoidance of doubt, where the Work is a musical composition or sound recording, the synchronization of the Work in timed-relation with a moving image ("synching") will be considered a Derivative Work for the purpose of this License.
+
+c. "Licensor" means the individual or entity that offers the Work under the terms of this License.
+
+d. "Original Author" means the individual or entity who created the Work.
+
+e. "Work" means the copyrightable work of authorship offered under the terms of this License.
+
+f. "You" means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exercise rights under this License despite a previous violation.
+
+### 2. Fair Use Rights
+
+Nothing in this license is intended to reduce, limit, or restrict any rights arising from fair use, first sale or other limitations on the exclusive rights of the copyright owner under copyright law or other applicable laws.
+
+### 3. License Grant
+
+Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below:
+
+a. to reproduce the Work, to incorporate the Work into one or more Collective Works, and to reproduce the Work as incorporated in the Collective Works;
+
+b. to create and reproduce Derivative Works;
+
+c. to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission the Work including as incorporated in Collective Works;
+
+d. to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission Derivative Works.
+
+The above rights may be exercised in all media and formats whether now known or hereafter devised. The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media and formats. All rights not expressly granted by Licensor are hereby reserved, including but not limited to the rights set forth in Section 4(d).
+
+### 4. Restrictions
+
+The license granted in Section 3 above is expressly made subject to and limited by the following restrictions:
+
+a. You may distribute, publicly display, publicly perform, or publicly digitally perform the Work only under the terms of this License, and You must include a copy of, or the Uniform Resource Identifier for, this License with every copy or phonorecord of the Work You distribute, publicly display, publicly perform, or publicly digitally perform. You may not offer or impose any terms on the Work that alter or restrict the terms of this License or the recipients' exercise of the rights granted hereunder. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties. You may not distribute, publicly display, publicly perform, or publicly digitally perform the Work with any technological measures that control access or use of the Work in a manner inconsistent with the terms of this License Agreement. The above applies to the Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Work itself to be made subject to the terms of this License. If You create a Collective Work, upon notice from any Licensor You must, to the extent practicable, remove from the Collective Work any credit as required by clause 4(c), as requested. If You create a Derivative Work, upon notice from any Licensor You must, to the extent practicable, remove from the Derivative Work any credit as required by clause 4(c), as requested.
+
+b. You may distribute, publicly display, publicly perform, or publicly digitally perform a Derivative Work only under the terms of this License, a later version of this License with the same License Elements as this License, or a Creative Commons iCommons license that contains the same License Elements as this License (e.g. Attribution-NonCommercial-ShareAlike 2.0 Japan). You must include a copy of, or the Uniform Resource Identifier for, this License or other license specified in the previous sentence with every copy or phonorecord of each Derivative Work You distribute, publicly display, publicly perform, or publicly digitally perform. You may not offer or impose any terms on the Derivative Works that alter or restrict the terms of this License or the recipients' exercise of the rights granted hereunder, and You must keep intact all notices that refer to this License and to the disclaimer of warranties. You may not distribute, publicly display, publicly perform, or publicly digitally perform the Derivative Work with any technological measures that control access or use of the Work in a manner inconsistent with the terms of this License Agreement. The above applies to the Derivative Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Derivative Work itself to be made subject to the terms of this License.
+
+c. If you distribute, publicly display, publicly perform, or publicly digitally perform the Work or any Derivative Works or Collective Works, You must keep intact all copyright notices for the Work and provide, reasonable to the medium or means You are utilizing: (i) the name of the Original Author (or pseudonym, if applicable) if supplied, and/or (ii) if the Original Author and/or Licensor designate another party or parties (e.g. a sponsor institute, publishing entity, journal) for attribution in Licensor's copyright notice, terms of service or by other reasonable means, the name of such party or parties; (iii) the title of the Work if supplied; (iv) to the extent reasonably practicable, the Uniform Resource Identifier, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work; and (v) consistent with Section 3(b), in the case of a Derivative Work, a credit identifying the use of the Work in the Derivative Work (e.g., "French translation of the Work by Original Author," or "Screenplay based on original Work by Original Author"). Such credit may be implemented in any reasonable manner; provided, however, that in the case of a Derivative Work or Collective Work, at a minimum such credit will appear where any other comparable authorship credit appears and in a manner at least as prominent as such other comparable authorship credit.
+
+d. For the avoidance of doubt, where the Work is a musical composition:
+
+i. Performance Royalties Under Blanket Licenses. Licensor reserves the exclusive right to collect, whether individually or via a performance rights society (e.g. ASCAP, BMI, SESAC), royalties for the public performance or public digital performance (e.g. webcast) of the Work if that performance is primarily intended for or directed toward commercial advantage or private monetary compensation.
+
+ii. Mechanical Rights and Statutory Royalties. Licensor reserves the exclusive right to collect, whether individually or via a music rights agency or designated agent (e.g. Harry Fox Agency), royalties for any phonorecord You create from the Work ("cover song") and distribute, subject to the compulsory license created by 17 USC Section 115 of the US Copyright Act (or the equivalent in other jurisdictions), if Your distribution of such cover song is primarily intended for or directed toward commercial advantage or private monetary compensation.
+
+e. Webcasting Rights and Statutory Royalties. For the avoidance of doubt, where the Work is a sound recording, Licensor reserves the exclusive right to collect, whether individually or via a performance-rights society (e.g. SoundExchange), royalties for the public digital performance (e.g. webcast) of the Work, subject to the compulsory license created by 17 USC Section 114 of the US Copyright Act (or the equivalent in other jurisdictions), if Your public digital performance is primarily intended for or directed toward commercial advantage or private monetary compensation.
+
+### 5. Representations, Warranties and Disclaimer
+
+UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.
+
+### 6. Limitation on Liability
+
+EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+### 7. Termination
+
+a. This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. Individuals or entities who have received Derivative Works or Collective Works from You under this License, however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License.
+
+b. Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above.
+
+### 8. Miscellaneous
+
+a. Each time You distribute or publicly digitally perform the Work or a Collective Work, the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License.
+
+b. Each time You distribute or publicly digitally perform a Derivative Work, Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License.
+
+c. If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties of this agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.
+
+d. No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent.
+
+e. This License constitutes the entire agreement between the parties with respect to the Work licensed here. There are no understandings, agreements or representations with respect to the Work not specified here. Licensor shall not be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Licensor and You.
+
+Creative Commons is not a party to this License, and makes no warranty whatsoever in connection with the Work. Creative Commons will not be liable to You or any party on any legal theory for any damages whatsoever, including without limitation any general, special, incidental or consequential damages arising in connection to this or any use of the Work. Notwithstanding the foregoing two (2) sentences, if Creative Commons has expressly identified itself as the Licensor hereunder, it shall have all rights and obligations of Licensor.
+
+Except for the limited purpose of indicating to the public that the Work is licensed under the CCPL, neither party will use the trademark "Creative Commons" or any related trademark or logo of Creative Commons without the prior written consent of Creative Commons. Any permitted use will be in compliance with Creative Commons' then-current trademark usage guidelines, as may be published on its website or otherwise made available upon request from time to time.
+
+Creative Commons may be contacted at https://creativecommons.org/.

package/README.md

@@ -95,3 +95,16 @@ ISC License - feel free to use in personal and commercial projects.
 ---
 
 **[View Documentation](https://dustinpoissant.github.io/kempo-css/)** | **[Report Issues](https://github.com/dustinpoissant/kempo-css/issues)**
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
+
+- Setting up your development environment
+- Code style and conventions
+- Testing guidelines
+- Pull request process
+
+## License
+
+This work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 2.0 Generic License](https://creativecommons.org/licenses/by-nc-sa/2.0/) - see the [LICENSE.md](LICENSE.md) file for details.

package/docs/.config.json

@@ -0,0 +1,17 @@
+{
+  "customRoutes": {
+    "/kempo.min.css": "../src/kempo.css",
+    "/kempo-hljs.min.css": "../src/kempo-hljs.css",
+    "/kempo-ui/**": "../node_modules/kempo-ui/dist/**",
+    "/icons/**": "../node_modules/kempo-ui/icons/**"
+  },
+  "middleware": {
+    "logging": {
+      "enabled": true,
+      "includeResponseTime": true
+    },
+    "security": {
+      "enabled": false
+    }
+  }
+}

package/docs/components/ThemePropertyInput.js

@@ -0,0 +1,47 @@
+import ShadowComponent from"/kempo-ui/components/ShadowComponent.js";import{html,css}from"/kempo-ui/lit-all.min.js";export default class ThemePropertyInput extends ShadowComponent{static properties={propName:{type:String,attribute:"prop-name"},value:{type:String},availableProperties:{type:Array,attribute:"available-properties"},mode:{type:String},initialColor:{type:String,attribute:"initial-color"}};static styles=css`
+    :host {
+      display: block;
+    }
+    label {
+      display: block;
+      margin-bottom: 0.25rem;
+    }
+    .input-wrapper {
+      display: flex;
+      gap: 0.5rem;
+      align-items: center;
+    }
+    .mode-select {
+      width: 100px;
+      flex-shrink: 0;
+    }
+    .value-input {
+      flex: 1;
+    }
+  `;constructor(){super(),this.propName="",this.value="",this.availableProperties=[],this.mode="color",this.initialColor=""}connectedCallback(){super.connectedCallback(),this.value?.startsWith("var(")&&(this.mode="var")}firstUpdated(){this.attachColorPickerListener()}updated(e){super.updated?.(e),this.attachColorPickerListener()}attachColorPickerListener(){if("color"===this.mode){const e=this.shadowRoot?.querySelector("k-color-picker");e&&!e._hasChangeListener&&(e._hasChangeListener=!0,e.addEventListener("change",this.handleColorChange),e.addEventListener("input",this.handleColorChange))}}handleModeChange=e=>{this.mode=e.target.value,"var"!==this.mode||this.value.startsWith("var(")?"color"===this.mode&&this.value.startsWith("var(")&&(this.value=this.initialColor||"#000000"):this.value=this.availableProperties[0]?`var(${this.availableProperties[0]})`:"",this.emitChange()};handleVarInput=e=>{const t=e.target.value;this.value=t.startsWith("var(")?t:`var(${t})`,this.emitChange()};handleColorChange=e=>{this.value=e.target.value,this.emitChange()};emitChange(){this.dispatchEvent(new CustomEvent("value-change",{detail:{propName:this.propName,value:this.value},bubbles:!0,composed:!0}))}render(){const e=`${this.propName}-datalist`,t=this.value?.startsWith("var(")?this.value.slice(4,-1).trim():"";return html`
+      <label>${this.propName}</label>
+      <div class="input-wrapper">
+        <select class="mode-select" .value=${this.mode} @change=${this.handleModeChange}>
+          <option value="var">Var</option>
+          <option value="color">Color</option>
+        </select>
+
+        ${"var"===this.mode?html`
+            <input 
+              class="value-input"
+              list=${e}
+              .value=${t}
+              @input=${this.handleVarInput}
+              placeholder="--property-name"
+            />
+            <datalist id=${e}>
+              ${this.availableProperties.map(e=>html`<option value=${e}></option>`)}
+            </datalist>
+          `:html`
+            <k-color-picker 
+              class="value-input"
+              value=${this.value}
+            ></k-color-picker>
+          `}
+      </div>
+    `}}customElements.define("k-theme-property-input",ThemePropertyInput);

package/docs/demo.inc.html

@@ -0,0 +1,182 @@
+<h1>Colors</h1>
+<h2>Background Colors</h2>
+<div class="d-f gap fw mb">
+  <div class="p bg-alt">bg-alt</div>
+  <div class="p bg-inv">bg-inv</div>
+  <div class="p bg-primary tc-on_primary">bg-primary</div>
+  <div class="p bg-secondary tc-on_secondary">bg-secondary</div>
+  <div class="p bg-success tc-on_success">bg-success</div>
+  <div class="p bg-warning tc-on_warning">bg-warning</div>
+  <div class="p bg-danger tc-on_danger">bg-danger</div>
+</div>
+<h2>Text Colors</h2>
+<div class="mb">
+  <p>Normal text color</p>
+  <p class="tc-muted">Muted text color</p>
+  <p class="tc-primary">Primary text color</p>
+  <p class="tc-secondary">Secondary text color</p>
+  <p class="tc-success">Success text color</p>
+  <p class="tc-warning">Warning text color</p>
+  <p class="tc-danger">Danger text color</p>
+</div>
+<div class="p bg-inv mb">
+  <p class="tc-inv">Inverse text color on inverse background</p>
+</div>
+
+<h1>Border Colors</h1>
+<div class="d-f gap fw mb">
+  <div class="p b">Default border</div>
+  <div class="p b bg-inv" style="border-color: var(--c_border__inv);">Inverse border</div>
+</div>
+
+<h1>Link Colors</h1>
+<p>
+  <a href="#">This is a link</a> - normal link styling
+</p>
+<div class="p bg-inv mb">
+  <a href="#" class="tc-link__inv">Inverse link</a> - for use on dark backgrounds
+</div>
+
+<h1>Buttons</h1>
+<h2>Button Types</h2>
+<div class="mb">
+  <button class="mb mr">button</button>
+  <input type="button" value="input" class="mb mr" />
+  <input type="submit" value="submit" class="mb mr" />
+  <a href="#" class="btn mb mr">a.btn</a>
+</div>
+
+<h2>Button Colors</h2>
+<div class="mb">
+  <button class="mb mr">Default</button>
+  <button class="primary mb mr">Primary</button>
+  <button class="secondary mb mr">Secondary</button>
+  <button class="success mb mr">Success</button>
+  <button class="warning mb mr">Warning</button>
+  <button class="danger mb mr">Danger</button>
+</div>
+
+<h2>Button Sizes</h2>
+<div class="d-f fw ai-center mb">
+  <button class="small mb mr">Small</button>
+  <button class="mb mr">Normal</button>
+  <button class="large mb mr">Large</button>
+</div>
+
+<h2>Button Groups</h2>
+<div class="btn-grp mb">
+  <button>One</button>
+  <button>Two</button>
+  <button>Three</button>
+</div>
+
+<h1>Inputs</h1>
+<div class="mb">
+  <label>Text Input</label>
+  <input type="text" placeholder="Enter text..." />
+</div>
+<div class="mb">
+  <label>Textarea</label>
+  <textarea placeholder="Enter longer text..."></textarea>
+</div>
+<div class="mb">
+  <label>Select</label>
+  <select>
+    <option>Option 1</option>
+    <option>Option 2</option>
+    <option>Option 3</option>
+  </select>
+</div>
+<div class="mb">
+  <input type="checkbox" id="demo-check1" />
+  <label for="demo-check1" class="checkbox">Checkbox 1</label>
+  <input type="checkbox" id="demo-check2" />
+  <label for="demo-check2" class="checkbox">Checkbox 2</label>
+</div>
+<div class="mb">
+  <input type="radio" name="demo-radios" id="demo-rad1" />
+  <label for="demo-rad1" class="checkbox">Radio 1</label>
+  <input type="radio" name="demo-radios" id="demo-rad2" />
+  <label for="demo-rad2" class="checkbox">Radio 2</label>
+</div>
+
+<h1>Focus & Effects</h1>
+<p>Click or tab to inputs and buttons to see focus styles.</p>
+<div class="mb">
+  <input type="text" class="mb mr" placeholder="Focus me..." />
+  <button class="mb mr">Focus me</button>
+  <button class="primary mb mr">Focus me</button>
+</div>
+<div class="p bg-alt drop-shadow mb" style="display: inline-block;">
+  Drop shadow effect
+</div>
+
+<h1>Typography</h1>
+<h2>Headings</h2>
+<h1>Heading 1</h1>
+<h2>Heading 2</h2>
+<h3>Heading 3</h3>
+<h4>Heading 4</h4>
+<h5>Heading 5</h5>
+<h6>Heading 6</h6>
+
+<h2>Paragraph Text</h2>
+<p>This is a paragraph of text demonstrating the base font family and size. The quick brown fox jumps over the lazy dog. Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
+<p><small>This is small text.</small></p>
+<p><strong>This is bold text.</strong></p>
+
+<h2>Monospace</h2>
+<p><code>Inline code uses the monospace font family.</code></p>
+<pre>Preformatted text also uses monospace.</pre>
+
+<h1>Spacing & Layout</h1>
+<h2>Key</h2>
+<ul class="mb">
+  <li><strong class="tc-success">Green</strong> = Padding</li>
+  <li><strong class="tc-warning">Orange</strong> = Margins</li>
+</ul>
+
+<h2>Padding</h2>
+<div class="mb">
+  <div class="d-ib bg-success mr mb p"><div class="d-ib bg-alt pq">p</div></div>
+  <div class="d-ib bg-success mr mb pt"><div class="d-ib bg-alt pq">pt</div></div>
+  <div class="d-ib bg-success mr mb pr"><div class="d-ib bg-alt pq">pr</div></div>
+  <div class="d-ib bg-success mr mb pb"><div class="d-ib bg-alt pq">pb</div></div>
+  <div class="d-ib bg-success mr mb pl"><div class="d-ib bg-alt pq">pl</div></div>
+  <div class="d-ib bg-success mr mb px"><div class="d-ib bg-alt pq">px</div></div>
+  <div class="d-ib bg-success mr mb py"><div class="d-ib bg-alt pq">py</div></div>
+</div>
+
+<h2>Margins</h2>
+<div class="mb">
+  <div class="d-ib bg-warning mr mb p"><div class="d-ib bg-alt pq">m</div></div>
+  <div class="d-ib bg-warning mr mb pt"><div class="d-ib bg-alt pq">mt</div></div>
+  <div class="d-ib bg-warning mr mb pr"><div class="d-ib bg-alt pq">mr</div></div>
+  <div class="d-ib bg-warning mr mb pb"><div class="d-ib bg-alt pq">mb</div></div>
+  <div class="d-ib bg-warning mr mb pl"><div class="d-ib bg-alt pq">ml</div></div>
+  <div class="d-ib bg-warning mr mb px"><div class="d-ib bg-alt pq">mx</div></div>
+  <div class="d-ib bg-warning mr mb py"><div class="d-ib bg-alt pq">my</div></div>
+</div>
+
+<h2>Container</h2>
+<p>The <code>.container</code> class limits content width.</p>
+
+<h1>Effects & Animation</h1>
+<h2>Border Radius</h2>
+<div class="mb">
+  <div class="d-ib bg-alt p mr mb b r">r</div>
+  <div class="d-ib bg-alt p mr mb b round">round</div>
+</div>
+<div class="mb">
+  <div class="d-ib bg-alt p mr mb b rtl">rtl</div>
+  <div class="d-ib bg-alt p mr mb b rtr">rtr</div>
+  <div class="d-ib bg-alt p mr mb b rbr">rbr</div>
+  <div class="d-ib bg-alt p mr mb b rbl">rbl</div>
+</div>
+<div class="mb">
+  <div class="d-ib bg-alt p mr mb b rt">rt</div>
+  <div class="d-ib bg-alt p mr mb b rb">rb</div>
+  <div class="d-ib bg-alt p mr mb b rl">rl</div>
+  <div class="d-ib bg-alt p mr mb b rr">rr</div>
+</div>
+<p><small><strong>Note:</strong> Add <code>0</code> suffix (e.g., <code>r0</code>, <code>rt0</code>) to cancel border radius.</small></p>