From 27a2650f5163434cd900b092ee62c8ed90b7c4ae Mon Sep 17 00:00:00 2001 From: xelaint Date: Wed, 16 Oct 2024 09:36:11 -0400 Subject: [PATCH 1/3] docs(design): update getting started docs --- libs/design/guides/getting-started.md | 110 +++++++++++--------------- 1 file changed, 44 insertions(+), 66 deletions(-) diff --git a/libs/design/guides/getting-started.md b/libs/design/guides/getting-started.md index 4031599641..d8d22555b0 100644 --- a/libs/design/guides/getting-started.md +++ b/libs/design/guides/getting-started.md @@ -1,96 +1,74 @@ -# Introduction -Get started with `@daffodil/design`, an Angular component library built for ecommerce with accessibility in-mind. With these first steps, we warmly welcome you to a library that will help you build elegant and accessible user interfaces without having to do everything by hand. +# Getting started +This guide is designed to touch upon the very basics of `@daffodil/design` to get you up and running quickly. It includes information on prerequisites, installation steps, and how to use a component. -## First Steps -This tutorial is designed to touch upon the very basics of the `@daffodil/design` library. First things first, you will need to [create a new Angular project](https://angular.io/cli) and [install the library](#installation). By the end of this tutorial, you will have created a basic Angular app that renders a simple `DaffHeroComponent` with a title and subtitle. +## Before you begin +`@daffodil/design` is designed to be used with Angular. Make sure [Angular CLI](https://angular.io/cli) has been installed before you begin. You'll also need a pakcage manager like [npm](https://www.npmjs.com/package/@daffodil/design) or [Yarn](https://yarnpkg.com/package?q=%40daffodil%2Fdesign&name=%40daffodil%2Fdesign). + +`@daffodil/design` uses [SASS](https://sass-lang.com/), so we recommend you learn it! ## Installation -`@daffodil/design` is designed to be used with Angular. If you have not already done so, [create a new Angular project](https://angular.io/cli). Afterwards, `@daffodil/design` can be installed using a [package manager](https://www.npmjs.com/package/@daffodil/design). +To install `@daffodil/design`, use the following commands in your terminal: -### npm +Install with npm: ```bash -npm install --save @daffodil/design @daffodil/core \ - @angular/animatio@^13.0.0 \ - @angular/cdk@^13.0.0 \ - @fortawesome/angular-fontawesome@^0.10.0 \ - @fortawesome/fontawesome-svg-core@^1.0.0 \ - @fortawesome/free-solid-svg-icons@^5.2.0 \ - @fortawesome/free-brands-svg-icons@^5.2.0 \ - @fortawesome/free-regular-svg-icons@^5.2.0 \ - modern-normalize@^0.5.0 +npm install @daffodil/design --save ``` -> If you are using Node.js v14 or higher, you can simply run: `npm install --save @daffodil/design` - -### Yarn +Install with Yarn: ```bash -yarn add @daffodil/design @daffodil/core \ - @angular/animatio@^13.0.0 \ - @angular/cdk@^13.0.0 \ - @fortawesome/angular-fontawesome@^0.10.0 \ - @fortawesome/fontawesome-svg-core@^1.0.0 \ - @fortawesome/free-solid-svg-icons@^5.2.0 \ - @fortawesome/free-brands-svg-icons@^5.2.0 \ - @fortawesome/free-regular-svg-icons@^5.2.0 \ - modern-normalize@^0.5.0 +yarn add @daffodil/design ``` -> If you are using Node.js v14 or higher, you can simply run: `yarn add @daffodil/design` - -### Modify Angular.json -Next, create a `styles.scss` in the root of the Angular app and modify the `angular.json`'s `projects.[my-app].architect.build.options.styles` to look as below. If SASS is already in use in the application and the stylesheet already exists, this step can be skipped. +## Set up your style environment +1. Create a `styles.scss` in the root of your Angular app. +2. Add the stylesheet to your `angular.json` file. This step can be skipped if SASS is already in use in the application and the stylesheet already exists. ```json -"styles": [ - "src/styles.scss" -], +"projects": { + "app-name": { + "architect": { + "build": { + "options": { + "styles": [ + "src/styles.scss" + ], + } + } + } + } +} ``` -> Note that `@daffodil/design` uses SASS, [so we recommend you learn it!](https://sass-lang.com/) - -### Add the Global Styles -There is a minimal required global style for `@daffodil/design` to operate effectively in all supported browsers. Update the `styles.scss` to include the following: +### Add global styles +There is a minimal required global style for the Daffodil Design System to operate effectively in all supported browsers. Update your `styles.scss` file to include the following: ```scss @forward '@daffodil/design/scss/global'; ``` -> For more information on our approach to these kinds of styles, see the ["Global Styles" guide.](/libs/design/guides/global-styles.md) +> For more information on our approach to these kinds of styles, see the [Global Styles guide.](/libs/design/guides/foundations/global-styles.md) -### Add a Theme -`@daffodil/design` is a themable component library. The components in the design library can be configured with customized colors in addition to a dark AND light mode for those same colors. +## Add a theme +`@daffodil/design` is a themable component library. The components in the design library can be configured with customized colors in addition to a dark and light mode for those same colors. No further configuration is needed if you choose to use `@daffodil/design`'s default theme. -> Are you excited by themes? So are we. +See the [Theming guide](/libs/design/scss/theming/README.md) if you'd like to define your own theme. -See the [Theming Docs](/libs/design/scss/theming/README.md) - -### Use a Component -In the `AppModule` of your Angular app, import the `DaffHeroModule` into the `NgModule`'s `imports` array. +## Use a component +Now you're ready to use Daffodil Design [components](/docs/design/components)! For example, here's how to use the [Hero](/libs/design/hero/README.md) component. ```ts -import { NgModule } from '@angular/core'; -import { BrowserModule } from '@angular/platform-browser'; - -import { AppComponent } from './app.component'; -import { DaffHeroModule } from '@daffodil/design/hero'; - -@NgModule({ +@Component({ + standalone: true, + selector: 'custom-component', + templateUrl: './custom-component.component.html', imports: [ - BrowserModule, - DaffHeroModule - ], - declarations: [ - AppComponent + DAFF_HERO_COMPONENTS, ], - bootstrap: [ - AppComponent - ] }) -export class AppModule {} +export class CustomComponent {} ``` -### Update the Template -With the module imported, the `AppComponent` template can be updated to render the component. +With the component imported, you can add it to your `CustomComponent` template like so: ```html @@ -103,5 +81,5 @@ With the module imported, the `AppComponent` template can be updated to render t ``` -## Next Steps -We've just walked through the basics of setting up the `@daffodil/design` library. There is much more to it than just the `DaffHeroComponent`. Check out the full list of available components, try and add them to your sample app, and imagine all the wonderful things you can now build! \ No newline at end of file +## Next steps +We've just walked through the basics of setting up `@daffodil/design`. There is much more to it than just the hero component. Check out the [full list of components](/docs/design/components), try and add them to your sample app, and imagine all the wonderful things you can now build! \ No newline at end of file From 393d1e4e09ed90b8b5bc555fc74bde9d703a94e1 Mon Sep 17 00:00:00 2001 From: xelaint Date: Wed, 16 Oct 2024 10:09:30 -0400 Subject: [PATCH 2/3] update docs --- libs/design/guides/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libs/design/guides/getting-started.md b/libs/design/guides/getting-started.md index d8d22555b0..99e3a4ba7a 100644 --- a/libs/design/guides/getting-started.md +++ b/libs/design/guides/getting-started.md @@ -4,7 +4,7 @@ This guide is designed to touch upon the very basics of `@daffodil/design` to ge ## Before you begin `@daffodil/design` is designed to be used with Angular. Make sure [Angular CLI](https://angular.io/cli) has been installed before you begin. You'll also need a pakcage manager like [npm](https://www.npmjs.com/package/@daffodil/design) or [Yarn](https://yarnpkg.com/package?q=%40daffodil%2Fdesign&name=%40daffodil%2Fdesign). -`@daffodil/design` uses [SASS](https://sass-lang.com/), so we recommend you learn it! +`@daffodil/design` is built with [Sass](https://sass-lang.com/), so we recommend you learn it! ## Installation To install `@daffodil/design`, use the following commands in your terminal: From ed1f444362fd788df459cc53142aa8a501c1ac81 Mon Sep 17 00:00:00 2001 From: xelaint Date: Thu, 17 Oct 2024 16:16:39 -0400 Subject: [PATCH 3/3] address comments --- libs/design/guides/getting-started.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/libs/design/guides/getting-started.md b/libs/design/guides/getting-started.md index 99e3a4ba7a..e8012a9f9a 100644 --- a/libs/design/guides/getting-started.md +++ b/libs/design/guides/getting-started.md @@ -49,9 +49,23 @@ There is a minimal required global style for the Daffodil Design System to opera > For more information on our approach to these kinds of styles, see the [Global Styles guide.](/libs/design/guides/foundations/global-styles.md) ## Add a theme -`@daffodil/design` is a themable component library. The components in the design library can be configured with customized colors in addition to a dark and light mode for those same colors. No further configuration is needed if you choose to use `@daffodil/design`'s default theme. +A theme must be configured in order for the components to work properly. The components in the design library can be configured with customized colors in addition to a dark and light mode for those same colors. -See the [Theming guide](/libs/design/scss/theming/README.md) if you'd like to define your own theme. +To use `@daffodil/design`'s default theme, include the following in your `styles.scss` file: + +```scss +@use '@daffodil/design/scss/theme' as daff; + +.daff-theme-light { + @include daff.daff-theme(daff.$theme); +} + +.daff-theme-dark { + @include daff.daff-theme(daff.$theme-dark); +} +``` + +See the [Theming guide](/libs/design/guides/foundations/theming.md) for more information on how to customize your own theme. ## Use a component Now you're ready to use Daffodil Design [components](/docs/design/components)! For example, here's how to use the [Hero](/libs/design/hero/README.md) component. @@ -82,4 +96,6 @@ With the component imported, you can add it to your `CustomComponent` template l ``` ## Next steps -We've just walked through the basics of setting up `@daffodil/design`. There is much more to it than just the hero component. Check out the [full list of components](/docs/design/components), try and add them to your sample app, and imagine all the wonderful things you can now build! \ No newline at end of file +We've just walked through the basics of setting up `@daffodil/design` and using the basic features of the Hero component. Now try to change the color of the [Hero](/libs/design/hero/README.md)! + +Check out the [full list of components](/docs/design/components), try and add them to your sample app, and imagine all the wonderful things you can now build! \ No newline at end of file