Incomplete typography documentation

davidkudera commented 3 years ago

Expected Behaviour

There is a note that typography.css file provides lit-html compliant version of the Spectrum Typography classes which I actually can't use directly in Lit. But it's also possible that I just don't understand the docs correctly.

I think that the documentation should include info about the .js files from styles directory that can be used in Lit

We're using the following in our components:

import spectrumHeadingStyles from '@spectrum-web-components/styles/heading.js';
import spectrumBodyStyles from '@spectrum-web-components/styles/body.js';
import spectrumTypographyStyles from '@spectrum-web-components/styles/typography.js';

@customElement('my-component')
class MyComponent extends LitElement
{
    public static styles: CSSResultGroup = [
        ...spectrumHeadingStyles,
        ...spectrumBodyStyles,
        ...spectrumTypographyStyles,
    ];
}

The order of styles is also important. typography.js must go after the other Spectrum styles otherwise, for example, headings will have margin: 0.

Actual Behaviour

There is no typography code sample in docs that I can use with LitElement.

Platform and Version

Windows 10
Chrome 91.0.4472.106
Webpack 5.38.1
Spectrum web components 0.22.1-alpha.2

Westbrook commented 3 years ago

Yes, our styles package need some serious documentation love! I'm not 100% sure where we'll be able to get to this, but you are definitely starting to use this more as expected. I've ported your code here to https://webcomponents.dev/edit/vpIdnA8V5JfzPp9LB2Pb/src/index.ts which may be the basis for an update in the future.

I realized as part of your earlier issue that the links back to Spectrum CSS for this are currently broken, sorry about that. Checkout https://opensource.adobe.com/spectrum-css/typography.html for more info. In that we're simply reexporting their rules, I'd prefer not to duplicate their documentation. Are there specific parts of the usage process that you're like to see to support using these styles?

For the usage of @spectrum-web-components/styles/typography.js, I think you've found a bug where we're over processing the contents of that file and removing some specificity that would otherwise allow these rules to be leveraged in either order. I'll see what I can hunt down on that and modify it for an upcoming release.

davidkudera commented 3 years ago

I think I was just really confused when I tried to correctly use the typography in our app. I tried a few different approaches but only now I'm satisfied with the result. That is after I found the body.js and heading.js files.

Before that I was importing @spectrum-web-components/styles/typography.js and @spectrum-css/typography/dist/index-vars.css in our Lit components. It resulted in a correctly styled text but this combination of packages and styles looked just strange:

import spectrumTypographyVarsStyles from '@spectrum-css/typography/dist/index-vars.css';
import spectrumTypographyStyles from '@spectrum-web-components/styles/typography.js';

@customElement('my-component')
class MyComponent extends LitElement
{
    public static styles: CSSResultGroup = [
        spectrumTypographyVarsStyles,
        ...spectrumTypographyStyles,
    ];
}

Basically I was "hunting" for any information about using typography in older issues (like this one https://github.com/adobe/spectrum-web-components/issues/964#issuecomment-712130742) and in CSS Spectrum documentation and combining them together.

So the specific parts I think I'm missing....:

an example of how to use spectrum styles from @spectrum-web-components/styles in Lit
some info about other style files (body.js, heading.js, code.js, detail.js) because the docs mentions only typography right now

Westbrook commented 3 years ago

Awesome. I think we're just about on the same page here. I can't promise anytime soon, but hopefully in the next month or two we can get this properly addressed.

adobe / spectrum-web-components