- Figma -
- Angular figma Core figma +
- + Angular Figma | + Core Figma
- Not yet available
- ESLint Rule
- Available, view documentation diff --git a/src/app/pages/accordion.page.ts b/src/app/pages/accordion.page.ts index f080c8d98b..0c1f38af35 100644 --- a/src/app/pages/accordion.page.ts +++ b/src/app/pages/accordion.page.ts @@ -10,7 +10,7 @@ import { DemoTabData } from '../components/demo.component'; @Component({ selector: 'app-accordion', template: ` -
- Clarity Core - Our design system’s journey to framework independence.
- Clarity’s future: user-focused, framework-independent, accessible, enterprise-ready, and open source.
- Level Up Your Application by Adopting Clarity Core @@ -74,4 +85,4 @@ import { Component } from '@angular/core'; `, }) -export class DifferencesPage {} +export class AdditionalLearningPage {} diff --git a/src/app/pages/adoption-tooling.page.ts b/src/app/pages/adoption-tooling.page.ts index 07ec453007..66462eb07e 100644 --- a/src/app/pages/adoption-tooling.page.ts +++ b/src/app/pages/adoption-tooling.page.ts @@ -13,7 +13,7 @@ ClarityIcons.addIcons(checkCircleIcon); @Component({ template: ` -
- Advantages -
- This allows applications to rework page by page and keep the scope of changes isolated. - -
- Disadvantages -
- Applications may find it challenging to add the additional time to incorporate Clarity Core as they work. -
- Advantages -
- When you batch changes of a single component, you can more easily see how a single component is utilized across the application and ensure consistency. - -
- Disadvantages -
- Some components cannot be migrated in complete isolation when they are used in combination with others, such as in forms or buttons in a wizard. -
- Advantages -
- Gives you all of the power of Clarity Core, better control and optimization of your code, and can unblock the way to faster development. - -
- Disadvantages -
- This can be a major investment depending on the size and complexity of your application. -
- Advantages -
- Gives you a single place to standardize and control Clarity across your application, and can better support preferred customizations and implementations. - -
- Disadvantages -
- This can be a big investment if you don't have a large enough application, or can add bloat to your application. -
- Evaluate customizations - Do you really need to set a custom color or override the default behaviors in Clarity? Given the ability to modify Clarity Angular is largely unstandardized, it may help if you can simplify by using Clarity as it was intended as much as possible to limit the number of changes you have to worry about with migration and updates. -
- Use proper theming - Clarity theming is different between Clarity Angular and Clarity Core, and if you are customizing the theme in a single manner you'll find it much easier to migrate. It might be worth investing some time to standardize theme adjustments and to follow our guidance about how to properly theme Clarity Angular before migration. -
- Review design customizations before coding - In cases where you've customized Clarity, ensure you audit the changes with your designers so everybody understands reasons they were made. In large applications it can be hard to understand why some things are the way they are, and reviewing before digging into things can help you prepare. -
Accordion
+Accordion
With expanded, disabled and expandable panels
+With expanded, disabled and expandable panels
Key Differences in Clarity Angular and Clarity Core
+Additional Learning
+ +Key Differences in Clarity Angular and Clarity Core
- Clarity Angular was designed to try and leverage many of the capabilities of Angular and it was aimed at solving problems with a certain approach. We had the intention to make a design system that also provided guard rails for developers to avoid common pitfalls. What we learned was those same guard rails acted like brick walls for certain valid use cases and made it harder to maintain. With Clarity Core, we've taken the learnings from our Clarity Angular architecture, blended in modern web standards, and crafted a consistent architecture that avoids the previous pitfalls and makes things easier to work with. + We designed Clarity Angular to try and leverage many of the capabilities of Angular, and it was aimed at + solving problems by using guard rails for developers to avoid common pitfalls. Unfortunately, what we learned + was those same guard rails acted like brick walls for certain valid use cases. And it made it harder to + maintain. With Clarity Core, we've taken the learnings from our Clarity Angular architecture, blended in + modern web standards, and crafted a consistent architecture that avoids the previous pitfalls and makes + things easier to work with.
How to learn more
+ Get started with Clarity Core + +Additional reading
- We have written more content in our blog about the differences and architectural choices with Clarity Core. We encourage you to familiarize yourself with them, as they are useful also to learn from to apply to your own applications. + We have written more content in our blog about the differences and architectural choices with Clarity Core. + We encourage you to familiarize yourself with them, as they are useful also to learn from to apply to your + own applications.
--
+
Adoption tooling
+Adoption tooling
Clarity Adoption ESLint plugin
diff --git a/src/app/pages/alert.page.ts b/src/app/pages/alert.page.ts index 0a366905bd..e967178826 100644 --- a/src/app/pages/alert.page.ts +++ b/src/app/pages/alert.page.ts @@ -10,7 +10,7 @@ import { DemoTabData } from '../components/demo.component'; @Component({ selector: 'app-alert', template: ` -
Alerts
+Alerts
Approaches for Adopting Clarity Core
+Additional Strategies
-- There are multiple ways that you can incorporate Clarity Core into your application. There are tradeoffs between each of them and the best choice may vary from application to application. We want to emphasize that Clarity Angular and Clarity Core are fully independent implementations and can be used side by side. No matter what approach you take, we are supporting Clarity Angular as long as there is widespread use. -
+Adopting Clarity Core
- This page provides a list of common adoption patterns that you can use to determine what approaches might work for you. In many cases, it will be best to blend several options or to forge your own path. If you find a new path that is not defined here, we'd be happy to share it if you can submit it in our GitHub Discussions. + There are multiple ways that you can incorporate Clarity Core into your application. There are + tradeoffs between each of them and the best choice may vary from application to application. We + want to emphasize that Clarity Angular and Clarity Core are fully independent implementations and + can be used side by side. No matter what approach you take, we are supporting Clarity Angular as + long as there is widespread use.
- - -Option 1 - Page by Page
-- In this pattern, the recommendation is that you'd incorporate Clarity Core into your applications page by page as you are doing other work. If your application has 100 pages or routes, then each time you make a new page or modify an existing one you can also incorporate some time to update the page to fully use Clarity Core. + This page provides a list of common adoption patterns that you can use to determine what approaches + might work for you. In many cases, it will be best to blend several options or to forge your own path. + If you find a new path that is not defined here, we'd be happy to share it if you can submit it in + our GitHub Discussions.
--
-
Option 2 - Component by Component
+Adoption strategy support
+ +Support method | +Page by Page | +Component by Component | +Single Rewrite | +Application Library | +
---|---|---|---|---|
Embedded engineering support | +||||
Slack Channels | +||||
Automation Tooling | +||||
Office Hours | +||||
Github Discussions | +
Page by Page Adoption: Recommended and supported
+ +
+ We recommend incorporating Clarity Core into your applications page by page as you are doing other work.
+ If your application has 100 pages or routes, then each time you make a new page or modify an existing one
+ you can also incorporate some time to update the page to fully use Clarity Core.
+
+
+ Advantages
+ This allows applications to rework page by page and keep the scope of changes isolated.
+ Full support of the Clarity team, specifically - having an engineer embedded to provide guidance
+
- Component by component means you'll start by replacing all copies of a Clarity Angular component with its Clarity Core counterpart. This might be the default option for most applications, especially in cases where you can do search and replace actions to update. Our adoption tooling is built to help identify uses of individual components and in cases we can automatically migrate them for you, so this can be appealing. + Clarity recognizes that a perfect path to adoption of Clarity Core does not exist. Each product using Clarity + is unique in of its own right, which is why we encourage adopting Clarity Core by using a page by page adoption + strategy, we also support various other adoption strategies. Each comes with its own set of various support avenues.
--
-
Option 3 - Single Rewrite
+Component by Component Adoption
+ +
+ Component by component means you'll start by replacing all copies of a Clarity Angular component with its
+ Clarity Core counterpart. This might be the default option for most applications, especially in cases
+ where you can do search and replace actions to update. Our adoption tooling is built to help identify
+ uses of individual components and in cases we can automatically migrate them for you, so this can be
+ appealing.
+
+
+ Advantages
+ When you batch changes of a single component, you can more easily see how a single component is utilized
+ across the application and ensure consistency.
+
+ Disadvantages
+ Some components cannot be migrated in complete isolation when they are used in combination with others,
+ such as in forms or buttons in a wizard.
+
Single Rewrite Adoption
+ +
+ Some applications may find it worthwhile to do a single rewrite session where they replace everything at once.
+ Smaller applications can be more successful here and it can help ensure that you have a consistent
+ implementation. This may be a larger one time investment, but it can simplify your application by avoiding
+ the need to think about both Clarity Angular and Clarity Core.
+
+
+ Advantages
+ Gives you all of the power of Clarity Core, better control and optimization of your code, and can unblock
+ the way to faster development.
+
+ Disadvantages
+ This can be a major investment depending on the size and complexity of your application.
+
App Library Adoption
+ +
+ Some applications have already incorporated a library into their application(s) that wrap Clarity (and other
+ dependencies). This may be done for a number of reasons, such as standardizing or extending customizations,
+ incorporating components into a larger workflow, or to have control for easy updates in the future. If you have a library, it is likely that you'd want to start by incorporating Clarity Core into it first before putting it into your application. If you don't have a library yet, you might want to consider it for some of the more complex components.
+
+
+ Advantages
+ Gives you a single place to standardize and control Clarity across your application, and can better support
+ preferred customizations and implementations.
+
+
+ Disadvantages
+ This can be a big investment if you don't have a large enough application, or can add bloat to your application.
+
Adoption strategy support
- Some applications may find it worthwhile to do a single rewrite session where they replace everything at once. Smaller applications can be more successful here and it can help ensure that you have a consistent implementation. This may be a larger one time investment, but it can simplify your application by avoiding the need to think about both Clarity Angular and Clarity Core. + Some applications have already incorporated a library into their application(s) that wrap Clarity (and other + dependencies). This may be done for a number of reasons, such as standardizing or extending customizations, + incorporating components into a larger workflow, or to have control for easy updates in the future. If you have a + library, it is likely that you'd want to start by incorporating Clarity Core into it first before putting it into + your application. If you don't have a library yet, you might want to consider it for some of the more complex + components.
- --
-
Option 4 - App Library
- -- Some applications have already incorporated a library into their application(s) that wrap Clarity (and other dependencies). This may be done for a number of reasons, such as standardizing or extending customizations, incorporating components into a larger workflow, or to have control for easy updates in the future. If you have a library, it is likely that you'd want to start by incorporating Clarity Core into it first before putting it into your application. If you don't have a library yet, you might want to consider it for some of the more complex components. -
- --
-
Handling app customizations of Clarity
-
- We know from supporting Clarity Angular over the past 5+ years that applications have found interesting ways to extend it and customize it for various needs and use cases. Clarity Angular was unable to use Shadow DOM when it was first created (since browser support wasn't widespread), and our Clarity UI styling was developed to intentionally allow teams access to the styling for cases where they could use Angular. The result is that flexiblity allowed applications to make progress while also opening the door to customizations and tweaks that Clarity could not anticipate. We have seen bug reports appear after we refactored some internal HTML or CSS within components when we didn't expect to impact applications but the nature of Angular allows teams to modify things that we considered internal.
+ Advantages
+ Gives you a single place to standardize and control Clarity across your application, and can better support
+ preferred customizations and implementations.
+
+ Disadvantages
+ This can be a big investment if you don't have a large enough application, or can add bloat to your application.
- To that end, if you have made customizations to Clarity components there are a few things to consider to help minimize friction and impact. -
+-
-
Badges
+Badges
Badge colours
+Badge colours
Badge in different colours
Badge status
+Badge status
Badges with all available statuses
Button
+Button
Primary button
+Primary button
Basic primary button
Solid buttons
+Solid buttons
All solid buttons
Outline buttons
+Outline buttons
All outline buttons
Inverse buttons
+Inverse buttons
Icon buttons
+Icon buttons
Loading buttons
+Loading buttons
Card
+Card
Card with title and body
+Card with title and body
Card media block
+Card media block
Checkbox
+Checkbox
Basic checkbox
+Basic checkbox
Example of more complex form structure
+Example of more complex form structure
Combobox
+Combobox
Datalist
+Datalist
Datalist with text items
+Datalist with text items
Reactive forms
+Reactive forms
Using Angular forms inside datalist
Dropdown
+Dropdown
Form
+Form
Horizontal
+Horizontal
Vertical
+Vertical
Compact
+Compact
Display helpers, errors and success messages
+Display helpers, errors and success messages
Clarity Core don't handle display of messages as error
or success
the same way as
Clarity Angular does. This is left up to the developer to control when a given message is visible or not and how
diff --git a/src/app/pages/getting-started.page.ts b/src/app/pages/getting-started.page.ts
index aafb6f397e..d98e066b74 100644
--- a/src/app/pages/getting-started.page.ts
+++ b/src/app/pages/getting-started.page.ts
@@ -5,57 +5,45 @@
*/
import { Component } from '@angular/core';
-import { StackblitzService } from '../components/stackblitz/stackblitz.service';
-import { SupportedTemplates } from '../templates';
@Component({
selector: 'app-home',
- providers: [StackblitzService],
template: `
-
Getting Started
+Get Started
-Who is this guide for?
+Adoption strategy
- This guide is for everyone that want and needs to adopt our new Core components into there existing Clarity - Angular application. It's designed to help you rework and adopt in the best way and still get the same result as - before. Developers will find this most useful, but we hope to also incorporate any details that might be useful - for designers as necessary. + Clarity supports you and your team during the adoption of Clarity Core. A part of our mutual success hinges on outlining + an adoption strategy alongside understanding how the Clarity team can assist. By adopting Clarity Core, with an adoption + strategy in place, coupled with the support we provide, we, together, can minimize duplication efforts and break-fix issues.
-How to use this guide?
- The guide is structured into sections, every section will provide examples based on our Angular components and - their Core counterparts. Into the form of guides, snippets and corner cases that will help you with the adoption - of the new components and workflows. It will help to start by reviewing the differences - and approaches to adopting Clarity Core. + There are multiple ways that you can incorporate Clarity Core into your application. There are tradeoffs between each of them, + and the best choice may vary from application to application. We want to emphasize that Clarity Angular and Clarity Core are fully + independent implementations and can be used side by side. No matter what approach you take, we support Clarity Angular as long as + there is widespread use.
-Where to find more information?
+Page by Page Adoption: Recommended and supported
+- This guide is updated regularly but won't have every detail about the Clarity Angular or Clarity Core APIs. Therefore you - should also be ready to reference both the Clarity Angular documentation and - Clarity Core documentation + We recommend incorporating Clarity Core into your applications page by page as you are doing other work. For example, if your + application has 100 pages or routes, then each time you make a new page or modify an existing one, you can also incorporate + some time to update the page to use Clarity Core fully.
-Project starters
-Below are few templates that could be used to start running Angular or Core based application.
+
+ Advantages
+ This allows applications to rework page by page and keep the scope of changes isolated.
+ Full support of the Clarity team, specifically - having an engineer embedded to provide guidance.
+
Header
+Header
Icons
+Icons
All available icon variants
+All available icon variants
Color states
+Color states
Rotation
+Rotation
Badges
+Badges
Input
+Input
Input with placeholder
+Input with placeholder
Input with label and placeholder
+Input with label and placeholder
Error and Info
+Error and Info
Input demos with info message and error message
Introduction
+Clarity Core for 2050
- Clarity began in 2016 as a design system built specifically for Angular, which we will call Clarity Angular. It is used by many of VMware's largest applications, and by other companies and applications outside of VMware. As Clarity's popularity and usage grew, so did requirements for Clarity to work well with other frameworks to help unify applications that don't use Angular. That led us to envision a new implementation of Clarity built on top of web components that can be utilized by any application. + We started Clarity to bring high quality and consistency to applications through a design system. + We've evolved the approach and quality with Clarity Core. Our components are designed to remain stable + for decades using web standards so that you can depend upon it for as long as your application needs.
-- This new version of Clarity is called Clarity Core, and it gave us the opportunity to reflect upon the successes of Clarity Angular and to improve areas that had been recurring challenges. When we built Clarity Angular originally, Angular was still in beta and best practices were yet to be defined for Angular. That led us to evolve some of our technical architecture over time, but it was challenging to bring the lessons we had learned along the way into some parts of Clarity Angular without causing major pain on applications who expected things to behave in certain ways. We wanted to condense all that we had learned with Clarity Angular and ensure that we carefully set forth a more consistent architecutre, address common pitfalls and gaps in capabilities, and simplify the implementations for easier integration. And in those goals, we believe we are delivering all of that and more with Clarity Core and are excited to help you get the most from Clarity with our CLarity Core components and patterns. -
+ -- So what about Clarity Angular? As you can imagine, two implementations of Clarity comes with significant investments in development and support. When we released Clarity v5, we announced that we've frozen Clarity Angular feature development. This has a number of benefits. First, we're committing to no breaking changes in Clarity Angular, so you can expect the components you are using today not to conflict with your usage of them. Second, we're continuing to bugfix and support issues with Clarity Angular, which means you'll still get the same (or perhaps even better) quality of support and stability you've come to expect with Clarity. Finally, we're going to continue to update as necessary to align with major Angular releases, so you aren't stuck on an older version of Angular due to compiler or TypeScript incompatibilities. All of this is to give applications confidence in using Clarity Angular for as long as they need to. -
-- As great as Clarity Angular is, we are excited about what Clarity Core can allow you to accomplish. For example, there are new features in the Clarity Core datagrid that were previously impossible with Clarity Angular. We're adding new components like the pagination and breadcrumb components as well. And finally, it's fully independent of frameworks and systematically built to maximize the lifetime of the components. We are building Clarity Core on top of web standards, which means that they will continue to work even if your frameworks of choice change over time. In the life of the web web standards are not removed just deprecated in favor of better choices. (Even the original Space Jam movie website works perfectly fine today as it did in the 1990s). This means we can confidently say that Clarity Core is future facing, with no expiration date. -
+We support your adoption process
+Automation, documentation, support
- Our objective with Clarity Core and this website specifically is to help you benefit from the improvements in quality, consistency, and framework independence that we've built in this modern implementation. We aim to support you with this interactive guide showing details about the way components are used in Clarity Angular and Clarity Core. We have also built tooling, such as our ESLint rules to help identify where you are using Clarity Angular and in some cases also to help automate the upgrade process. We will also be adding some case studies and expanding this guide with more stories about how applications have approached incorporating Clarity Core. + Using Clarity Core is an investment in the future. It may take some time to bring Clarity Core + fully into your applications. We understand. We support you in that journey with automation to + help detect and rewire existing code, document samples of how Clarity Angular and Clarity Core + are used, and continue to support both Clarity Angular and Clarity Core libraries.
-- We're proud of both Clarity Angular and Clarity Core, and know that teams depend upon one or both of these in their daily work. Our community has been active in engaging with suggesting features, reporting and fixing issues, and advocating for us. We thank you for that and know we wouldn't be where we are today without the open source community. If you have questions or insights relatd to this guide or adopting Clarity Core, we'd love to see you join us in GitHub Discussions and sharing your notes. We can improve and expand with your inputs and together move forward with Clarity! -
+ + +Clarity Documentation
+ `, }) export class IntroPage { - + } diff --git a/src/app/pages/label.page.ts b/src/app/pages/label.page.ts index 4193829349..8f84e2eb97 100644 --- a/src/app/pages/label.page.ts +++ b/src/app/pages/label.page.ts @@ -10,24 +10,24 @@ import { DemoTabData } from '../components/demo.component'; @Component({ selector: 'app-label', template: ` -Labels
+Labels
Simple label with text
+Simple label with text
Outline labels with badge
+Outline labels with badge
Clickable outline labels
+Clickable outline labels
Outline labels without badge
+Outline labels without badge
Labels with status
+Labels with status
Labels with colour background fill
Clarity Core Adoption Guide
+Clarity Core Adoption Guide
-- A simple, intuitive guide for helping teams adopt and migrate from Clarity Angular to Clarity Core. -
-- Why Clarity Core -
-Clarity for 2050
-- Clarity was started with the goal of bringing high quality and consistency to applications through a design system. We've evolved the approach and quality with Clarity Core. Using web standards, our components are designed to remain stable for decades so you can depend upon it for as long as your application needs. -
- Read the reasons behind Clarity Core - Understand differences in Clarity Core - Look at approaches to adoption -+ A simple, intuitive guide for helping teams adopt and migrate from Clarity Angular to Clarity Core. +
+- How we support you -
-Automation, documentation, support
-- We know that using Clarity Core is an investment in the future, and may take some time to bring Clarity Core fully into your applications. We plan to support you in that journey with automation to help detect and rewire existing code, document samples of how Clarity Angular and Clarity Core are used, and continue to support both Clarity Angular and Clarity Core libraries. -
- Review the components - Incorporate our automation tooling - Ask questions or share feedback -List
+List
Ordered list
diff --git a/src/app/pages/modal.page.ts b/src/app/pages/modal.page.ts index b560bbbb02..0b200917bf 100644 --- a/src/app/pages/modal.page.ts +++ b/src/app/pages/modal.page.ts @@ -10,7 +10,8 @@ import { DemoTabData } from '../components/demo.component'; @Component({ selector: 'app-modal', template: ` -Modal
+Modal
+@@ -20,11 +21,11 @@ import { DemoTabData } from '../components/demo.component';
With title, body and footer
+With title, body and footer
Closable
+Closable
In some cases there is a need to prevent the user from closing the modal. To achieve this there is an option for diff --git a/src/app/pages/overview.page.ts b/src/app/pages/overview.page.ts index bee0093414..9b3e87765b 100644 --- a/src/app/pages/overview.page.ts +++ b/src/app/pages/overview.page.ts @@ -9,23 +9,23 @@ import { componentRoutes } from '../app-routing.module'; @Component({ styles: [ - `.item { border: .0625rem solid var(--cds-global-color-gray-400); border-radius: .1875rem; }`, - `.item-img { max-height: 5rem; max-width: 50%; }`, + `.item { border: .0625rem solid var(--cds-global-color-gray-400); border-radius: .1875rem;}`, + `.item-img { max-width: 160px; min-width: 160px; max-height: 100px; min-height: 100px; }` ], template: ` -
Clarity Components
+Clarity Components
+
+
+
{{component.path | menuTitle}}
-
-
{{component.path | menuTitle}}
-
Password
+Password
With label
+With label
Password with Reactive form
+Password with Reactive form
Progress bar
+Progress bar
Radio
+Radio
Range
+Range
With label and info message
+With label and info message
Select
+Select
With 3 elements and label
+With 3 elements and label
Reactive form
+Reactive form
Signpost
+Signpost
Spinner
+Spinner
Stack View
+Stack View
Stepper
+Stepper
Tab
+Tab
Table
+Table
Example Builder
+Example Builder
Generate a demo project from a already existing template to test and learn how diff --git a/src/app/pages/textarea.page.ts b/src/app/pages/textarea.page.ts index 1fb73e7f7c..fb1a96106c 100644 --- a/src/app/pages/textarea.page.ts +++ b/src/app/pages/textarea.page.ts @@ -10,16 +10,16 @@ import { DemoTabData } from '../components/demo.component'; @Component({ selector: 'app-textarea', template: ` -