Create Stunning Style Guides with Eleventy | 11ty Meetup

Table of Contents

1. Introduction
   1. About the Eleventy Style Guide Generator
   2. Overview of the Table of Contents
   3. Background of the Developer
2. Why I Built the Generator
   1. XKCD Comic Inspiration
   2. Benefits of Component-Based Development
   3. Simplicity and Native Integration of Eleventy
3. Features of the Generator
   1. Itemization of Design Tokens
   2. Configuration and Variation of Components
   3. WebC Component Support
   4. Standalone Documentation Pages
4. Live Demo Examples
   1. Personal Site Design System
   2. Different Site with Varied Colors and Fonts
5. File and Folder Organization
   1. Design Tokens and JSON Files
   2. Utopia Tool for Generating Tokens
   3. Component Configuration and Config Files
   4. Design System Layouts
   5. Atomic Elements and Static Content
6. How Component Data is Collected
   1. Gathering Component Configuration Files
   2. Reducing and Formatting Component Details
   3. Generating the Tree Structure for the Design System
7. Working with Web Components
   1. Integration of Web Components from EveryLayout
   2. Creating a Web Component with HTML and JavaScript
   3. Examples of Web Component Usage
8. WebC HTML-only Component Examples
   1. Creating a Card Component
   2. Configuring Variations of the Card Component
   3. Showcase of Card Component Variations
9. Non-WebC Component Example
   1. Creating a Quote Component with Nunjucks
   2. Configuring the Quote Component
   3. Showcase of the Quote Component
10. Acknowledgments and Additional Resources
    1. Projects and People to Thank
    2. Links for More Reading and Resources

Introduction

The Eleventy Style Guide Generator is a powerful tool created by Steve Woodson, a highly experienced web developer based in Chicago, Illinois. This tool aims to simplify and streamline the process of documenting and testing components in web development projects. In this article, we will explore the various aspects of the Eleventy Style Guide Generator, including its features, demonstrations, file organization, component data collection, usage of web components, HTML-only component examples, and more. Join us on this Journey to uncover the intricacies of this innovative tool and discover how it can enhance your web development workflow.

Why I Built the Generator

XKCD Comic Inspiration

As the creator of the Eleventy Style Guide Generator, I must admit that I was inspired by an XKCD comic that resonated with me. It depicted the concept of taking matters into one's own hands and creating new solutions when dissatisfied with existing options. This comic fueled my determination to devise a generator that would address some of the shortcomings I observed in other tools. However, I embarked on a period of introspection and reflection before committing to this endeavor, questioning whether it was truly worth the effort and if it would genuinely benefit others.

Benefits of Component-based Development

During my contemplation, I found myself drawn to the concept of component-based development, a familiar concept resonant with frameworks like Vue and Svelte. Having worked on numerous projects within this framework, I recognized the value of having an automated system to document and test components in isolation. It became clear to me that a tool like the Eleventy Style Guide Generator, which simplifies this process and promotes modular, responsive design, could significantly assist developers.

Simplicity and Native Integration of Eleventy

While appreciating more extensive solutions such as Storybook, I acknowledged that they may introduce unnecessary complexity for certain projects. In many instances, a simple tool that allows for itemization, documentation, and testing of components using Eleventy would suffice. Thus, I decided to focus my efforts on creating a generator that seamlessly integrates with Eleventy and offers just the right level of functionality, omitting unnecessary complexity. This decision aligns with my career philosophy of adhering to standards-aligned terminology and finding the most effective, efficient solutions for each project's unique requirements.

Features of the Generator

The Eleventy Style Guide Generator offers a range of powerful features that simplify the process of documenting and testing components in web development projects. These features include:

1. Itemization of Design Tokens: The generator visually itemizes JSON-formatted design tokens, such as color, response, fluid Scale, and sizing. While it is not mandatory, using tokens enables automatic itemization within the generator.

2. Configuration and Variation of Components: The generator supports the itemization of components and their variations based on a simple configuration file format. This feature allows for flexibility and customization when showcasing different versions of a component.

3. WebC Component Support: The generator provides built-in support for WebC components and offers examples to assist with their implementation. Although WebC is not a strict requirement, it serves as the impetus behind the generator's development and is highly recommended.

4. Standalone Documentation Pages: The generator also supports the creation of standalone documentation pages. These pages are ideal for displaying foundational HTML elements or providing more curated explanations of the design system's details.

These features, combined with Eleventy's native capabilities, empower developers to efficiently manage and showcase their components, ensuring a streamlined and organized web development workflow.

Live Demo Examples

To provide a comprehensive understanding of the Eleventy Style Guide Generator in action, let's explore two live demo examples. These demonstrations offer a glimpse into the generator's capabilities and how it seamlessly integrates into web development projects.

Personal Site Design System

The first demo showcases the design system created for my personal Website. This design system features a variety of components, such as headers and sidebars, and includes a visually itemized representation of the design tokens. By examining this demo, You will gain insights into the power and versatility of the Eleventy Style Guide Generator.

Different Site with Varied Colors and Fonts

In the Second demo, we explore a different website that utilizes the Eleventy Style Guide Generator. This site features a distinct color scheme and font selection, showcasing how the generator accommodates varying design preferences. Despite the differences in aesthetics, the underlying components remain consistent, highlighting the flexibility and adaptability of the generator.

These live demos offer firsthand experiences of how the Eleventy Style Guide Generator can enhance your web development projects. By visualizing the generator in action, you will gain a deeper appreciation for its features and potential benefits.

File and Folder Organization

Efficient file and folder organization is essential for maintaining a structured and easily navigable project. The Eleventy Style Guide Generator employs a well-defined structure, ensuring optimum organization and Clarity throughout the development process.

Design Tokens and JSON Files

All design tokens, including JSON files, are centralized within the "data/designTokens" directory. This organization provides easy access to the JSON files, which are utilized by the generator to generate itemized design tokens.

To streamline the process of generating design tokens, the generator leverages the Utopia tool. Utopia is exceptionally effective for fluid typography and spacing, contributing to the efficiency and accuracy of design token generation.

Component Configuration and Config Files

All components and their configuration files are stored within the "includes/components" directory. The generator automatically detects and processes these configuration files, enabling seamless integration of the components into the style guide.

To ensure consistent configuration, a corresponding ".config.js" file is required for each component. This file contains essential information about the component, such as its title, Context, preview class, and variants. By adhering to this structure, developers can easily manage and showcase their components within the style guide.

Design System Layouts

The Eleventy Style Guide Generator provides dedicated folders for design system layouts. These layouts are prefixed with "ds" and reside in the "standardLayouts" directory. Leveraging these pre-defined layouts facilitates the creation of consistent and visually Cohesive design system pages.

Atomic Elements and Static Content

To accommodate atomic elements and static content, the generator offers several options. Developers can store these elements in the root folder of the design system or in subfolders based on their organizational preferences. By incorporating atomic elements and static content within the project structure, developers can Create comprehensive and self-contained style guides.

By following this meticulous file and folder organization scheme, developers can easily locate and manage various components, design tokens, layouts, and static content. This disciplined approach lays the foundation for efficient collaboration and streamlined development processes.

How Component Data is Collected

The Eleventy Style Guide Generator employs a robust process to Collect component data. Through this framework, the generator ensures accurate and comprehensive representation of each component within the style guide.

Gathering Component Configuration Files

The first step in the data collection process revolves around identifying and gathering component configuration files. To automate this process, the generator leverages the "require-glob" Package, which actively searches for files matching the specified pattern, typically "includes/components/**/.config.js". This approach ensures that all Relevant component configuration files are accurately detected.

Reducing and Formatting Component Details

After identifying the component configuration files, the generator utilizes a reducer function to collate and format the relevant information. By employing this reducer, the generator generates a detailed object that includes all necessary data about each component. This object serves as the foundational structure for the comprehensive representation of the design system within the style guide.

Generating the Tree Structure for the Design System

To showcase the design system's structure and hierarchy, the generator employs the generated component data object. This hierarchy is visually represented within the style guide's sidebar, allowing users to easily navigate and explore the various components and their variations. The tree structure creates a logical and intuitive flow, optimizing the user experience and facilitating efficient component discovery.

By employing this meticulous data collection framework, the Eleventy Style Guide Generator ensures that the style guide accurately reflects the components' details and intricacies. This comprehensive representation empowers developers to effectively showcase their components and provide valuable documentation for their projects.

Working with Web Components

Web components offer a powerful means of creating reusable and encapsulated HTML elements. The Eleventy Style Guide Generator embraces the potential of web components and provides native support for their integration into web development projects. Let's explore how the generator facilitates the utilization of web components.

Integration of Web Components from EveryLayout

The Eleventy Style Guide Generator enables developers to effortlessly integrate web components from external sources. One notable example is the sidebar component sourced from EveryLayout. By leveraging this pre-existing web component, developers can add an aesthetically pleasing and functional sidebar to their projects. The seamless integration of web components enhances the overall user experience within the style guide and the final website.

Creating a Web Component with HTML and JavaScript

The generator also supports the creation of web components using HTML and JavaScript. These components offer increased flexibility and customization possibilities, as developers can tailor them specifically to their project requirements. By linking the associated CSS and JavaScript files, developers can transform HTML elements into dynamic and reusable web components. This native support of web components further expands the generator's versatility and adaptability.

Examples of Web Component Usage

To showcase the capabilities of web components, the Eleventy Style Guide Generator features multiple examples. These examples illustrate the usage of web components within a style guide, highlighting the various functionalities and design aesthetics they bring to web development projects.

These examples solidify the Eleventy Style Guide Generator's commitment to supporting web components and encouraging developers to explore their potential. By harnessing the power of web components, developers can elevate their projects and deliver truly innovative web experiences.

WebC HTML-only Component Examples

While web components offer fantastic flexibility and power, the Eleventy Style Guide Generator also allows for the creation of HTML-only components. These components do not rely on WebC or intricate code structures, making them accessible even to developers less familiar with complex web frameworks. Let's Delve into the process of creating and utilizing HTML-only components within the generator.

Creating a Card Component with Nunjucks

The generator facilitates the creation of HTML-only components by leveraging Nunjucks templates. Nunjucks allows developers to create reusable HTML templates supplemented with the necessary logic and data bindings. Using Nunjucks, developers can combine HTML, CSS, and JavaScript to create elegant and functional components.

In this example, we demonstrate the creation of a card component using Nunjucks. The card component includes various slots for the image, content, and citation. The Nunjucks file acts as the foundation for constructing the card component's structure and incorporating dynamic content.

Configuring Variations of the Card Component

To maximize flexibility and usability, the generator allows developers to configure variations of HTML-only components. Developers can define different versions of the card component by specifying variations within the component's configuration file. These variations adapt the component to display alternative content or modify its appearance based on specific requirements.

In the case of the card component, developers have the freedom to customize the positioning of the image, content, and citation. By tailoring these variations, developers can seamlessly integrate the card component into their projects' diverse design systems.

Showcase of Card Component Variations

By leveraging the flexibility of HTML-only components, the Eleventy Style Guide Generator empowers developers to showcase various versions of the card component. These variations demonstrate different configurations, enabling users to Visualize how the component can adapt to specific design needs.

Through these variations, developers can present an illustrious array of options and inspire creativity within their projects. The Eleventy Style Guide Generator fosters innovation and encourages developers to explore the full potential of HTML-only components.

Non-WebC Component Example

While the Eleventy Style Guide Generator primarily focuses on supporting WebC components, it remains flexible and compatible with non-WebC components. Developers who prefer or require alternative approaches can seamlessly integrate their chosen solutions into the generator and benefit from its comprehensive documentation and testing capabilities. Let's explore an example of a non-WebC component within the generator.

Creating a Quote Component with Nunjucks

In this example, we showcase the creation of a quote component using Nunjucks templates. By utilizing Nunjucks, developers can harness the power of HTML templating to create reusable and versatile components. The quote component's configuration file specifies various attributes, such as the body and citation. These attributes populate the Nunjucks template with the corresponding data, generating the quote component's output.

The Eleventy Style Guide Generator facilitates the seamless integration of non-WebC components, allowing developers to build and showcase diverse components tailored to their project requirements.

Showcase of the Quote Component

By incorporating the quote component within the style guide, developers can effectively illustrate its functionality and design. Through the Eleventy Style Guide Generator's documentation capabilities, users gain a deeper understanding of the component's implementation and potential use cases.

The Eleventy Style Guide Generator embraces flexibility and universality, empowering developers to showcase the entirety of their component repertoire. By offering compatibility with both WebC and non-WebC components, the generator caters to the diverse needs and preferences of web developers.

Acknowledgments and Additional Resources

The Eleventy Style Guide Generator owes its existence to the invaluable contributions of numerous projects and individuals within the web development community. These projects and people have Shaped and influenced the generator, enriching its functionality and enhancing its capabilities. Let's express our gratitude and explore further resources for continued learning and inspiration.

Projects and People to Thank

The Eleventy Style Guide Generator would not be possible without the remarkable contributions of various projects and individuals. Special thanks go to the following:

• Eleventy: The foundational framework that enables the generator's seamless integration and empowers developers to streamline their web development workflow.
• WebC: The impetus behind the generator's development and the driving force behind the creation of modular and responsive components.
• Utopia: The powerful tool for generating design tokens, facilitating the efficient creation of visually appealing and responsive web projects.
• Build Excellent Websites: The inspiration for the design tokens feature, providing a solid foundation for the generator's design token capabilities.
• Cube CSS: The innovative approach to CSS organization, influencing the generator's strategies for structuring and organizing CSS files.
• Trys Mudford: The creator of an inspiring self-documented design system, which served as a reference and inspiration for the Eleventy Style Guide Generator.
• Small CSS and EveryLayout: The sources of essential base styles and web components that enhance the generator's compatibility with various design systems and components.

These projects and individuals have played pivotal roles in shaping the Eleventy Style Guide Generator, and their contributions are highly appreciated. We encourage you to explore these projects further and delve into the wealth of knowledge they provide.

Links for More Reading and Resources

To facilitate further exploration and learning, we compiled a list of valuable resources related to the Eleventy Style Guide Generator. These resources provide additional insights, information, and guidance, making them excellent reference materials for developers interested in maximizing the generator's potential. The resources include:

• GitHub Source: Access the generator's source code and dive into the details of its implementation.
• Demo Sites: Explore live examples showcasing the power and versatility of the Eleventy Style Guide Generator in the context of complete websites.
• Announcements on the Developer's Blog: Delve deeper into the generator's development journey and gain additional insights into its features and capabilities.

These resources serve as pillars of knowledge and aid developers in fully harnessing the Eleventy Style Guide Generator's capabilities.

Thank you for joining us on this enlightening journey through the Eleventy Style Guide Generator. By implementing this powerful tool, developers can elevate their web development projects to new heights, streamlining their processes and delivering exceptional user experiences. Embrace the potential, explore the possibilities, and witness the positive impact the Eleventy Style Guide Generator can have on your web development workflow.

Highlights

• The Eleventy Style Guide Generator simplifies the documentation and testing of components in web development projects.
• It offers features such as design token itemization, component configuration and variation, WebC component support, and standalone documentation pages.
• Live demo examples showcase the generator's capabilities and integration into diverse websites.
• File and folder organization allows for efficient management of design tokens, component configuration files, layouts, atomic elements, and static content.
• Component data collection follows a structured framework, resulting in accurate and comprehensive representation within the style guide.
• Web components can be seamlessly integrated, both from external sources and through HTML and JavaScript creation.
• HTML-only components can be created and customized using Nunjucks templates.
• Non-WebC components can still be utilized within the generator, expanding its compatibility and flexibility.
• The Eleventy Style Guide Generator is a result of the collaborative efforts of multiple projects and individuals.
• Further reading and resources are available for continued learning and inspiration.

FAQ

Q: Is the Eleventy Style Guide Generator compatible with other web frameworks? A: Yes, the Eleventy Style Guide Generator is designed to be compatible with a variety of web frameworks. While it seamlessly integrates with Eleventy and offers native support for WebC components, it can also accommodate non-WebC components and other web frameworks through its flexible configuration options.

Q: Can I use the generator for a personal website with custom design tokens? A: Absolutely! The Eleventy Style Guide Generator supports customization and allows you to utilize your own custom design tokens. By following the generator's file organization structure and properly configuring your design tokens, you can effectively showcase your unique design system within the style guide.

Q: Will the Eleventy Style Guide Generator work with my preferred CSS organization method? A: Yes, the Eleventy Style Guide Generator is flexible and adaptable to various CSS organization methods. Whether you follow the principles of cube CSS or another CSS organization approach, you can easily incorporate your preferred method within the generator's file structure. This compatibility ensures that the generator caters to the unique needs and preferences of web developers.

Q: Can I customize the appearance of the style guide? A: Yes, the Eleventy Style Guide Generator offers customization options that empower you to tailor the appearance of the style guide to your liking. By modifying the CSS files and adjusting the configuration, you can achieve a style guide that aligns perfectly with your project's branding and visual identity.

Q: Is the Eleventy Style Guide Generator suitable for large-scale projects with numerous components? A: Absolutely! The Eleventy Style Guide Generator is designed to handle large-scale projects with ease. By following the generator's file organization structure and employing proper component configuration, you can seamlessly manage and showcase a vast collection of components within the style guide. The generator's tree structure and intuitive navigation enable efficient exploration and discovery of numerous components, ensuring a smooth workflow for your project.

Q: Can the Eleventy Style Guide Generator be used in conjunction with other documentation tools? A: Yes, the Eleventy Style Guide Generator can be seamlessly integrated with other documentation tools to augment your project's documentation capabilities. Whether you combine it with tools like Storybook or other documentation frameworks, the generator's flexibility allows for harmonious integration, empowering you to create comprehensive and cohesive project documentation.