Component Directory Structure #6
Comments
|
This is the set of requirements we put together to track the various pieces of a component. It needs to be updated because there are many many more files and more data associated with a component imho - but this is a good start for the basics of what's required Feature: Cross-team and cross-technology pattern
As a developer
I want to document how we will store and distribute my team's patterns
So that my team can document, store, and build upon my team's efforts
Scenario: Module exports an object
Given that I have a pattern for use in multiple projects and scenarios
And that my pattern will be distributed as an npm module
And that my pattern must include a content model
And that my pattern may be designed in Sketch
And that my pattern may be designed in Adobe Illustrator
And that my pattern may be built using nunjucks templating
And that my pattern may be built as a React component
And that my pattern may be built as an Angular 1x component
And that my pattern may be built as an Angular 2x component
And that my pattern may include a style sheet
When I release my pattern for use
Then it should be released as an npm module
And said module should export an object
And said object may have a key who's value represents the Sketch file
And said object may have a key who's value represents the AI file
And said object must have a key who's value represents the canonical version
And said object may have a key who's value represents the nunjucks version
And said object may have a key who's value represents the React version
And said object may have a key who's value represents the Angular 1x version
And said object may have a key who's value represents the Angular 2x version
And said object should have a key who's value represents the content model
And said object should have a key who's value is a function which returns an object of content
And said content object should return example content
And said content object should be addressable by key
And said content function should accept parameters to vary what is returned.
Scenario: Pattern has dependencies
Given that I have an interface that my healthcare ux pattern that includes a form
And that my app is built using components
And that portions of the form may be built from components in an external component library
When my app imports my healthcare pattern
Then it should import the external library as a dependency
and my app should have access to all styles required by my pattern.
Scenario: Pattern is connected to a clearly defined User Story
Given that I have a pattern for use in multiple projects and scenarios
And that my pattern should have been created according to one or more user stories
And that said stories must be written for a specific user
And that said users should be one of our pre-determined personas
When I am creating documentation on my pattern's creation
And said pattern should be distributed with documentation
And said documentation should include all relevant user stories
And said documentation should include references to represented personas
And said documentation may be in the module's README.
Scenario: Canonical Design
Given that I need a source-of-truth to represent my pattern's design
And that said source should include example content
And that said source should have UX to match the user story
And that said source should have a design that follows Watson Health guidelines
And that said guidelines can be enforced using Sketch libraries
When I want an design representing the new feature as described in the user story
Then I need my design to be created in Sketch
And said design will be represented by a single Sketch file
And said Sketch file should include all libraries which enforce Watson Health guidelines
And said Sketch file should accept content
And said content should match the story's content model
And said design should represent all of the story's UX requirements
And said design should conform to Watson Health guidelines
And said design should represent all content variations.
Scenario: Canonical Implementation
Given that I need a source-of-truth to represent my pattern's implementation
And that said source should include example content
And that said source should be styled to match the design
When I want an example representing my pattern
Then I need my example to be written in semantic HTML
And said HTML should contain all elements required by my pattern
And said elements should contain all attributes required by my pattern
And said pattern should accept content
And said content should conditionally change the viewed pattern
And said example should be tested to match the user story requirements.
Scenario: Pattern is implementation agnostic
Given that I have a pattern for use in multiple projects and scenarios
And that said projects may be implemented using disparate technology solutions
And that said solutions should create consistent HTML markup
And that said solutions should follow a consistent element class naming structure
When I am creating an implementation-specific version of my pattern
Then my new version should have the same markup as the canonical version
And said version should accept content
And said content should conditionally change the viewed pattern
And said version should match the canonical when viewed by a user
And said version should match the canonical when unit-tested
And said version should be tested to match the user story requirements.
Scenario: Pattern should match external versions
Given that my pattern may be implemented by external repositories
And that external implementations should produce the same HTML as my canonical version
When testing my pattern
Then my tests should include the external implementation
And the external version should be run through the default unit tests for my implementation
And there should be a way to determine inconsistencies between implementations.
Scenario: Anatomy of a pattern
Given that I have a pattern for use in multiple projects and scenarios
When I am creating a home for my pattern
Then that pattern should be use-able via multiple technologies
And said pattern should be distributed with a README
And said README should include usage instructions
And said pattern's module should include documentation
And said pattern's module should export an object
And said pattern's module should include a canonical design
And said pattern's module should include a canonical implementation
And said pattern's module may include multiple implementations
And said module's patterns should be tested against external pattern implementations
And said multiple implementations must pass the same tests as the canonical version.Cross-team and cross-technology pattern
|
|
Items specific to the
In a
Main pain point: in this current setup the only way to verify the exportable tests is by working in parallel with a |
demos (variants) sourceThere should be a canonical set of demos (variants). For instance, button has multiple They are:
If all of these items are something a developer should expect to be available in their framework of choice, then there should be a configuration that breaks down each variant the should be part of a given component's spec. These would also be reflected within the selectors object. Point being...under and generating a config objectThis line: in our could align by accepting this: or conversely, the Handlebars version could align by exchanging helps the tests!Both of the above get us closer to a canonical set of variants (kinds? demos?). So your helps the shares :)This also means that if carbon-components-meow has a new button variant, and that variant is something approved for global use across the carbon frameworks by being accepted by IBM design...then it could be moved to |
|
@scottnath here is my updated list. My only concern is the template in the spec repo...
|
|
Just a heads up @scottnath, in this example for the React API: <Button variant="danger" icon="information">We actually have to move away from the icon name API as it's a pattern that isn't easily tree-shaken 😞 In order to implement, we have to do a pattern like: import AllIcons from 'icons-package';
export default function MyComponent({ icon }) {
return (
<>
<p>Some text</p>
{AllIcons[icon]}
</>
);
}Which means that we have a runtime lookup 😞 |
|
Just catching up here, but one thing I've been thinking about is if spec should export anything, or if it should be an aggregator. One hope of mine with this project would be to support a view like: https://test262.report/ where, instead of engines, we should framework implementations and their corresponding coverage. The way we could report on frameworks is by having them PR into spec. A structure could be:
The project itself would be responsible for three assets:
|
|
@joshblack I'm following the idea you have of it containing the reports for the each implementation/framework and I think the report like test262 is a very interesting idea. I do think that the spec repo would be a bit more though than just these reports. To my understanding this repo was meant to be the location of all things that are common despite what JS framework is being used. I'm also a little curious as to what the work flow would be for this to make sure that what's in spec and what's in the framework specific repo are always in sync. As far as the spec document goes I think we need to do something different than the aria site. It's not clear what "user needs" are, expected behavior, etc and in general it's a bit daunting. During my a11y meetings the one consistent thing that people talk about is how the standards documentation is not clear. I think there are aspects of what they are doing that would could certainly pull in but that we will want to re-think the structure and content that is actually included. |
|
@joshblack I don't see why we couldn't have top-level Side note: maybe the spec adherence reporting would better live in a separate repo where we track other design system KPIs for adoption and contributions. Framework spec coverage will depend on strong contributions after all. @scottnath @elizabethsjudd I move discussion on generate functions to #8. Looking forward to hearing your thoughts. |
canonical set of demos (variants). Written how?@elizabethsjudd this goes to your questions about how we create the static HTML. These should not be files written by a human. Ideally, these files would be autogenerated from a framework. It seems though, that this is not really something that would be only coming from one framework: Scenario: angular team finds and fixes a bug in buttonSteps to change canonical HTML:
points being:
configuration file for demos (variants). Written how?Luckily all the frameworks use javascript, so it can be an ingestible object. This would require some level common API between the systems though. Sounds like that might be tricky in the short term though, so this may fall on the tests. tracking scenarios within a framework
|
|
@joshblack @scottnath @mattrosno See this #8 (comment) for more around Scott's comment on |
@elizabethsjudd I think something that would be valuable is to decouple implementation details from the spec. It would be great if we could have it so that anyone could implement the spec, but we have a canonical implementation that follows it if you don't want to do it custom. Decoupling things in this way could mean that we could have potentially multiple implementations that could work in various contexts that still adhere to the spec. One example could be around styles, where one style implementation would want to leverage sass while another one wants to leverage a CSS-in-JS solution. @mattrosno Would 100% make sense to export the runner if implementations wanted to use it in their own projects 👍 Could easily see new framework XYZ wanting to follow TDD with: /* Test file */
// Proposed API
import { runner, runComponent } from '@carbon/spec';
describe('ComponentName', () => {
test('spec', () => {
// Run specific component check
runComponent('ComponentName', /* mount fn */);
});
});And working interactively to make sure it hits all the necessary rulesets. |
|
@joshblack all the conversations we've had to this point were that Sass was also going to live in this repo. Breaking out Sass to allow something like you're describing does make sense in flexibility, it's just new to these conversations and we'd want to figure out where Sass would live than. |
|
I think in terms of workflow it'd be great if we could keep the styles colocated with a canonical implementation versus in the spec, mostly because it can be easier to create component permutations and debug interactive styles when combined with a framework or environment like fractal. Things like exporting selectors then can be tied to the style implementation versus the spec. This could be valuable if, once again, teams want to drive forward with an alternative style implementation that still adheres to the spec. This could help if things like selectors mean different things to a framework using sass versus something using CSS-in-JS. |
|
As we get deeper into the proof of concept, I hope this will be more clear. Should (1) the spec be used just for component requirements, exported test runner and test reporting purposes? Or (2) should the spec also provide configuration objects ( I'll continue to push on (2) in the proof of concept. |
Is your feature request related to a problem? Please describe.
Component directory structure should be architected in such a way that the content of a component, be it files or data, is consistently written and structured and available for straightforward external usage.
Describe the solution you'd like
Documentation which we can refer to which says what files would be where. ie: sass, written requirements, requirements-tests would be in
spec, handlebars templates in carbon-components, react versions in carbon-c-react, etc.Also...regardless of the location, there should be an easy way to import these files and component-data from a single location. So, if I pulled in carbon-spec/src/accordion I could find that files like user-requirements.feature, index.scss (instead of _accordion.scss), _mixins.scss (etc) within that directory. There could also be a node file, index.js, which would output data required by the component - for instance content models, objects describing each variant or scenario, etc.
I'll add a comment below which contains the
gherkinwe used when architecting our component directories.Describe alternatives you've considered
n/a
Acceptance Criteria
The text was updated successfully, but these errors were encountered: